tadabut 0.2.0 → 0.4.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 +354 -45
- package/dist/index-mZisu7MG.d.ts +605 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +14 -33
- package/dist/react.js +60 -38
- package/dist/src-DWwW61Yo.js +1189 -0
- package/package.json +5 -4
- package/dist/index-D2g9_Fd9.d.ts +0 -603
- package/dist/src-C4vgw-1w.js +0 -982
|
@@ -0,0 +1,605 @@
|
|
|
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
|
+
/** The Delete button. */
|
|
110
|
+
readonly delete: string;
|
|
111
|
+
/** Asked in the row before deleting it. */
|
|
112
|
+
readonly deleteQuestion: string;
|
|
113
|
+
/** The button that confirms a delete. */
|
|
114
|
+
readonly confirm: string;
|
|
115
|
+
/** The button that keeps the row instead. */
|
|
116
|
+
readonly keep: string;
|
|
117
|
+
/** Under a row when `onDelete` throws something that isn't an `Error`. */
|
|
118
|
+
readonly deleteFailed: string;
|
|
119
|
+
/** Shown in a select while its options load. */
|
|
120
|
+
readonly loading: string;
|
|
121
|
+
/** Under a row when `onSave` throws something that isn't an `Error`. */
|
|
122
|
+
readonly saveFailed: string;
|
|
123
|
+
/** Under a new row when `onAdd` throws something that isn’t an `Error`. */
|
|
124
|
+
readonly addFailed: string;
|
|
125
|
+
/** Under a select whose options failed to load. */
|
|
126
|
+
readonly loadFailed: string;
|
|
127
|
+
/** An empty field with `required`. */
|
|
128
|
+
readonly required: string;
|
|
129
|
+
/** A text that doesn't match `pattern`. */
|
|
130
|
+
readonly patternMismatch: string;
|
|
131
|
+
/** A text shorter than `minLength`. */
|
|
132
|
+
readonly tooShort: (min: number) => string;
|
|
133
|
+
/** A text longer than `maxLength`. */
|
|
134
|
+
readonly tooLong: (max: number) => string;
|
|
135
|
+
/** A number below `min`. */
|
|
136
|
+
readonly tooSmall: (min: number) => string;
|
|
137
|
+
/** A number above `max`. */
|
|
138
|
+
readonly tooLarge: (max: number) => string;
|
|
139
|
+
/** A date before `min`, given as `'YYYY-MM-DD'`. */
|
|
140
|
+
readonly tooEarly: (min: string) => string;
|
|
141
|
+
/** A date after `max`, given as `'YYYY-MM-DD'`. */
|
|
142
|
+
readonly tooLate: (max: string) => string;
|
|
143
|
+
};
|
|
144
|
+
/** One choice in a select. */
|
|
145
|
+
type SelectOption<Value> = {
|
|
146
|
+
/** What the user sees. */
|
|
147
|
+
readonly label: string;
|
|
148
|
+
/** What gets saved in the row. */
|
|
149
|
+
readonly value: Value;
|
|
150
|
+
};
|
|
151
|
+
/** The second argument of an `options` function. */
|
|
152
|
+
type OptionsContext = {
|
|
153
|
+
/**
|
|
154
|
+
* Aborted when the result isn't needed anymore (the field above changed
|
|
155
|
+
* again, or the row closed). Pass it to `fetch`.
|
|
156
|
+
*/
|
|
157
|
+
readonly signal: AbortSignal;
|
|
158
|
+
};
|
|
159
|
+
/** Can return the list directly or a promise of it. */
|
|
160
|
+
type SelectOptionsLoader<Value, Row> = (row: Row, context: OptionsContext) => readonly SelectOption<Value>[] | Promise<readonly SelectOption<Value>[]>;
|
|
161
|
+
/** Fields that hold a string, so they can store a label. */
|
|
162
|
+
type TextKeys<Row> = { [Key in keyof Row]: Row[Key] extends string | null | undefined ? Key : never; }[keyof Row] & string;
|
|
163
|
+
/**
|
|
164
|
+
* A dropdown for `string`, `number` or `boolean` columns. Option values must
|
|
165
|
+
* have the column's type (`1`, not `'1'`). A value that matches no option
|
|
166
|
+
* gives `null`.
|
|
167
|
+
*
|
|
168
|
+
* `options` is a list, or a function of the row. With a function you can set
|
|
169
|
+
* `dependsOn`: when that field changes, this select is cleared and reloaded.
|
|
170
|
+
*
|
|
171
|
+
* @example
|
|
172
|
+
* { type: 'select', options: [{ value: 1, label: 'Morocco' }] }
|
|
173
|
+
*
|
|
174
|
+
* {
|
|
175
|
+
* type: 'select',
|
|
176
|
+
* dependsOn: 'countryId',
|
|
177
|
+
* labelProp: 'cityName',
|
|
178
|
+
* options: (row, { signal }) => fetchCities(row.countryId, signal),
|
|
179
|
+
* }
|
|
180
|
+
*/
|
|
181
|
+
type SelectEditor<Value, Row> = BaseEditor & {
|
|
182
|
+
/** Picks this editor. */
|
|
183
|
+
readonly type: "select";
|
|
184
|
+
/**
|
|
185
|
+
* Where to save the picked label, like `'cityName'`. The cell shows that
|
|
186
|
+
* field too. While options are loading, the old label is kept.
|
|
187
|
+
*/
|
|
188
|
+
readonly labelProp?: TextKeys<Row>;
|
|
189
|
+
} & ({
|
|
190
|
+
/** The choices, in order. */
|
|
191
|
+
readonly options: readonly SelectOption<Value>[];
|
|
192
|
+
/** Only allowed when `options` is a function. */
|
|
193
|
+
readonly dependsOn?: never;
|
|
194
|
+
} | {
|
|
195
|
+
/** Gives the choices for the open row. */
|
|
196
|
+
readonly options: SelectOptionsLoader<Value, Row>;
|
|
197
|
+
/** When this field changes, the select is cleared and `options` runs again. */
|
|
198
|
+
readonly dependsOn?: keyof Row & string;
|
|
199
|
+
});
|
|
200
|
+
/**
|
|
201
|
+
* For `string` columns. The options work like the HTML attributes.
|
|
202
|
+
*
|
|
203
|
+
* @example
|
|
204
|
+
* { type: 'text', minLength: 2, maxLength: 50 }
|
|
205
|
+
*/
|
|
206
|
+
type TextEditor = BaseEditor & {
|
|
207
|
+
/** Picks this editor. */
|
|
208
|
+
readonly type: "text";
|
|
209
|
+
/** Fewest characters allowed. */
|
|
210
|
+
readonly minLength?: number;
|
|
211
|
+
/** Most characters allowed. */
|
|
212
|
+
readonly maxLength?: number;
|
|
213
|
+
/** Must match the whole value, like `'[A-Z]{2}[0-9]{4}'`. No slashes, no `^`/`$`. */
|
|
214
|
+
readonly pattern?: string;
|
|
215
|
+
};
|
|
216
|
+
/**
|
|
217
|
+
* Which editors a column can have, from its value type:
|
|
218
|
+
*
|
|
219
|
+
* | Column value | Built-in editors |
|
|
220
|
+
* | ------------- | ------------------ |
|
|
221
|
+
* | `string` | text, date, select |
|
|
222
|
+
* | `number` | number, select |
|
|
223
|
+
* | `boolean` | checkbox, select |
|
|
224
|
+
*
|
|
225
|
+
* `custom` works on anything. Nullable columns get the same editors as
|
|
226
|
+
* non-nullable ones.
|
|
227
|
+
*/
|
|
228
|
+
type EditorFor<Value, Row> = EditorForValue<NonNullable<Value>, Row> | CustomEditor<Value>;
|
|
229
|
+
/** The built-in editors for a non-null value type. */
|
|
230
|
+
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;
|
|
231
|
+
/**
|
|
232
|
+
* Works on every editor. An empty value fails `required` and skips every
|
|
233
|
+
* other check. Otherwise the editor's own rules (`min`, `maxLength`…) run,
|
|
234
|
+
* then `validate`. The first error wins.
|
|
235
|
+
*
|
|
236
|
+
* @example
|
|
237
|
+
* {
|
|
238
|
+
* type: 'number',
|
|
239
|
+
* required: true,
|
|
240
|
+
* min: 18,
|
|
241
|
+
* validate: (value, row) =>
|
|
242
|
+
* row.active && value !== null && value > 65
|
|
243
|
+
* ? 'Active employees must be 65 or younger'
|
|
244
|
+
* : undefined,
|
|
245
|
+
* }
|
|
246
|
+
*/
|
|
247
|
+
type ValidationOptions<Row, Value> = {
|
|
248
|
+
/** Does nothing on a checkbox, which is never empty. */
|
|
249
|
+
readonly required?: boolean;
|
|
250
|
+
/**
|
|
251
|
+
* Return an error message, or `undefined` if the value is fine. `value`
|
|
252
|
+
* can be `null` even on non-nullable columns, since empty inputs give
|
|
253
|
+
* `null`.
|
|
254
|
+
*/
|
|
255
|
+
readonly validate?: (value: Value | null, row: Row) => string | undefined;
|
|
256
|
+
};
|
|
257
|
+
/**
|
|
258
|
+
* A table column. The `editor` has to fit the type of `prop`, so a number
|
|
259
|
+
* field can't get a text input. Columns without an editor are read-only.
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* const columns: Column<Employee>[] = [
|
|
263
|
+
* { title: 'ID', prop: 'id' },
|
|
264
|
+
* { title: 'Age', prop: 'age', editor: { type: 'number', required: true, min: 18 } },
|
|
265
|
+
* ];
|
|
266
|
+
*/
|
|
267
|
+
type Column<Row extends object> = { readonly [Key in keyof Row & string]: ColumnFor<Row, Key>; }[keyof Row & string];
|
|
268
|
+
/** One column, for one field. `Column` is the union of these. */
|
|
269
|
+
type ColumnFor<Row extends object, Key extends keyof Row & string> = {
|
|
270
|
+
/** Header text. */
|
|
271
|
+
readonly title: string;
|
|
272
|
+
/** The field this column shows. */
|
|
273
|
+
readonly prop: Key;
|
|
274
|
+
/** Makes the column editable. Leave it out for a read-only column. */
|
|
275
|
+
readonly editor?: EditorFor<Row[Key], Row> & ValidationOptions<Row, Row[Key]>;
|
|
276
|
+
/**
|
|
277
|
+
* The cell's text when the row isn't open. It's shown as text, not HTML.
|
|
278
|
+
* Search uses it; sorting still uses the raw value.
|
|
279
|
+
*
|
|
280
|
+
* @example
|
|
281
|
+
* render: (value) => `${value} MAD`
|
|
282
|
+
*/
|
|
283
|
+
readonly render?: (value: Row[Key], row: Row) => string;
|
|
284
|
+
/** Like `'60px'` or `'20%'`. */
|
|
285
|
+
readonly width?: string;
|
|
286
|
+
/** Hidden columns still keep their value in the row, but can't be edited. */
|
|
287
|
+
readonly visible?: boolean;
|
|
288
|
+
/** `false` turns off sorting by this column. */
|
|
289
|
+
readonly orderable?: boolean;
|
|
290
|
+
/** `false` leaves this column out of the search. */
|
|
291
|
+
readonly searchable?: boolean;
|
|
292
|
+
/** Classes for the cells (header too), not for the input. */
|
|
293
|
+
readonly className?: string;
|
|
294
|
+
};
|
|
295
|
+
/** The second argument of `onSave`. */
|
|
296
|
+
type SaveContext<Row extends object> = {
|
|
297
|
+
/** The row as it was before editing. */
|
|
298
|
+
readonly previous: Row;
|
|
299
|
+
};
|
|
300
|
+
/** How rows are edited. */
|
|
301
|
+
type EditingOptions = {
|
|
302
|
+
/**
|
|
303
|
+
* `'single'` (default) allows one open row at a time. `'multiple'` allows
|
|
304
|
+
* any number, each saved on its own.
|
|
305
|
+
*/
|
|
306
|
+
readonly mode?: "single" | "multiple";
|
|
307
|
+
/**
|
|
308
|
+
* Adds an Edit/Save/Cancel column at the end. Defaults to `true`. Turn it
|
|
309
|
+
* off if you open rows yourself with `edit()`. The Delete button still
|
|
310
|
+
* shows if `onDelete` is set.
|
|
311
|
+
*/
|
|
312
|
+
readonly button?: boolean;
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* Extra CSS classes for the table and its buttons. They're added next to the
|
|
316
|
+
* `tdb-` classes, not instead of them.
|
|
317
|
+
*
|
|
318
|
+
* @example
|
|
319
|
+
* // Bootstrap 5
|
|
320
|
+
* {
|
|
321
|
+
* table: 'table table-striped table-hover',
|
|
322
|
+
* button: 'btn btn-sm',
|
|
323
|
+
* edit: 'btn-outline-primary',
|
|
324
|
+
* save: 'btn-primary',
|
|
325
|
+
* cancel: 'btn-outline-secondary',
|
|
326
|
+
* delete: 'btn-outline-danger',
|
|
327
|
+
* confirm: 'btn-danger',
|
|
328
|
+
* keep: 'btn-outline-secondary',
|
|
329
|
+
* }
|
|
330
|
+
*/
|
|
331
|
+
type TableClassNames = {
|
|
332
|
+
/** On the `<table>`. */
|
|
333
|
+
readonly table?: string;
|
|
334
|
+
/** Every button. */
|
|
335
|
+
readonly button?: string;
|
|
336
|
+
/** Edit button only. */
|
|
337
|
+
readonly edit?: string;
|
|
338
|
+
/** Save button only. */
|
|
339
|
+
readonly save?: string;
|
|
340
|
+
/** Cancel button only. */
|
|
341
|
+
readonly cancel?: string;
|
|
342
|
+
/** Delete button only. */
|
|
343
|
+
readonly delete?: string;
|
|
344
|
+
/** The button that confirms a delete. */
|
|
345
|
+
readonly confirm?: string;
|
|
346
|
+
/** The button that keeps the row instead. */
|
|
347
|
+
readonly keep?: string;
|
|
348
|
+
};
|
|
349
|
+
/**
|
|
350
|
+
* Any {@link https://datatables.net/reference/option/ | DataTables option},
|
|
351
|
+
* extensions included, except the ones Tadabut has to own: `data`,
|
|
352
|
+
* `columns`, `columnDefs` (use the column options), and `ajax`/`serverSide`
|
|
353
|
+
* (load rows yourself and call `setData`).
|
|
354
|
+
*
|
|
355
|
+
* @example
|
|
356
|
+
* { order: [[1, 'asc']], pageLength: 20, language: { search: 'Rechercher :' } }
|
|
357
|
+
*/
|
|
358
|
+
type DataTablesSettings = Omit<Config, "data" | "columns" | "columnDefs" | "ajax" | "serverSide">;
|
|
359
|
+
/** Options for `new Tadabut()`. */
|
|
360
|
+
type TadabutOptions<Row extends object> = {
|
|
361
|
+
/** The rows. The array is copied, never changed. */
|
|
362
|
+
readonly data: readonly Row[];
|
|
363
|
+
/** The columns, in order. */
|
|
364
|
+
readonly columns: readonly Column<Row>[];
|
|
365
|
+
/**
|
|
366
|
+
* The field that identifies a row, like `'id'`. Values must be unique.
|
|
367
|
+
* Required as soon as a column has an `editor`.
|
|
368
|
+
*/
|
|
369
|
+
readonly rowId?: keyof Row & string;
|
|
370
|
+
/** How rows are edited. */
|
|
371
|
+
readonly editing?: EditingOptions;
|
|
372
|
+
/** Your classes for the table and buttons. */
|
|
373
|
+
readonly classNames?: TableClassNames;
|
|
374
|
+
/** DataTables' own options, passed through. */
|
|
375
|
+
readonly dataTables?: DataTablesSettings;
|
|
376
|
+
/**
|
|
377
|
+
* Tadabut's own texts, like `fr`. Whatever you leave out stays in English.
|
|
378
|
+
*
|
|
379
|
+
* @example
|
|
380
|
+
* texts: { ...fr, save: 'Valider' }
|
|
381
|
+
*/
|
|
382
|
+
readonly texts?: Partial<Texts>;
|
|
383
|
+
/**
|
|
384
|
+
* Called with the edited row once it passes validation. May be async.
|
|
385
|
+
*
|
|
386
|
+
* Return a row to replace the edited one (useful for fields the server
|
|
387
|
+
* sets, like `updatedAt`), or nothing to keep it. Throw to reject the
|
|
388
|
+
* save: the row stays open and the error message is shown under it.
|
|
389
|
+
*/
|
|
390
|
+
readonly onSave?: (row: Row, context: SaveContext<Row>) => Row | void | Promise<Row | void>;
|
|
391
|
+
/**
|
|
392
|
+
* Called with a new row once it passes validation. May be async.
|
|
393
|
+
*
|
|
394
|
+
* Return the saved row, usually with its id from the server, or nothing
|
|
395
|
+
* to keep the row as typed. Either way it must have its `rowId` field, or
|
|
396
|
+
* Tadabut throws an error. Throw to reject the add: the row stays open and
|
|
397
|
+
* the error message is shown under it.
|
|
398
|
+
*
|
|
399
|
+
* The row is partial because it isn't saved yet: the id, and columns
|
|
400
|
+
* without an editor, are only there if you passed them to `add()`.
|
|
401
|
+
*
|
|
402
|
+
* @example
|
|
403
|
+
* onAdd: async (row) => {
|
|
404
|
+
* const res = await fetch('/api/employees', { method: 'POST', body: JSON.stringify(row) });
|
|
405
|
+
* return res.json();
|
|
406
|
+
* }
|
|
407
|
+
*/
|
|
408
|
+
readonly onAdd?: (row: Partial<Row>) => Row | void | Promise<Row | void>;
|
|
409
|
+
/**
|
|
410
|
+
* Called when a row is deleted. May be async. Throw to stop the delete:
|
|
411
|
+
* the row stays and the error message is shown under it.
|
|
412
|
+
*
|
|
413
|
+
* The Delete button only shows when this is set.
|
|
414
|
+
*/
|
|
415
|
+
readonly onDelete?: (row: Row) => void | Promise<void>;
|
|
416
|
+
/**
|
|
417
|
+
* What happens before a row is deleted with the Delete button. By default
|
|
418
|
+
* the row asks "Delete this row?" with two buttons. `false` deletes right
|
|
419
|
+
* away. A function replaces the question with yours: return `true` to
|
|
420
|
+
* delete. May be async, for a modal.
|
|
421
|
+
*
|
|
422
|
+
* `delete()` from code never asks.
|
|
423
|
+
*
|
|
424
|
+
* @example
|
|
425
|
+
* confirmDelete: (row) => window.confirm(`Delete ${row.name}?`)
|
|
426
|
+
*/
|
|
427
|
+
readonly confirmDelete?: false | ((row: Row) => boolean | Promise<boolean>);
|
|
428
|
+
};
|
|
429
|
+
/**
|
|
430
|
+
* A DataTables table with row editing.
|
|
431
|
+
*
|
|
432
|
+
* @typeParam Row - Usually inferred from `data`.
|
|
433
|
+
*
|
|
434
|
+
* @example
|
|
435
|
+
* const table = new Tadabut(container, {
|
|
436
|
+
* data: [{ id: 1, name: 'Amina' }],
|
|
437
|
+
* rowId: 'id',
|
|
438
|
+
* columns: [
|
|
439
|
+
* { title: 'ID', prop: 'id' },
|
|
440
|
+
* { title: 'Name', prop: 'name' },
|
|
441
|
+
* ],
|
|
442
|
+
* });
|
|
443
|
+
*/
|
|
444
|
+
declare class Tadabut<Row extends object> {
|
|
445
|
+
/** The DataTables instance. */
|
|
446
|
+
private readonly dataTable;
|
|
447
|
+
/** The `<table>` Tadabut created. */
|
|
448
|
+
private readonly tableEl;
|
|
449
|
+
/** The field that identifies a row. */
|
|
450
|
+
private readonly rowId;
|
|
451
|
+
/** The user's columns, without the actions column. */
|
|
452
|
+
private readonly columns;
|
|
453
|
+
/** `editing` with its defaults filled in. */
|
|
454
|
+
private readonly editing;
|
|
455
|
+
/** The user's classes, or `{}`. */
|
|
456
|
+
private readonly classNames;
|
|
457
|
+
/** The user's texts over English. */
|
|
458
|
+
private readonly texts;
|
|
459
|
+
/** The user's save callback. */
|
|
460
|
+
private readonly onSave;
|
|
461
|
+
/** The user's add callback. */
|
|
462
|
+
private readonly onAdd;
|
|
463
|
+
/** The user's delete callback. */
|
|
464
|
+
private readonly onDelete;
|
|
465
|
+
/** What the Delete button does before deleting. */
|
|
466
|
+
private readonly confirmDelete;
|
|
467
|
+
/** Whether the actions column exists. */
|
|
468
|
+
private readonly hasActions;
|
|
469
|
+
/** Whether any column has an editor. */
|
|
470
|
+
private readonly hasEditor;
|
|
471
|
+
/** Open rows, by row id. */
|
|
472
|
+
private readonly sessions;
|
|
473
|
+
/** Rows waiting for `onDelete`, by row id. */
|
|
474
|
+
private readonly deleting;
|
|
475
|
+
/** The row `add()` opened, if any. */
|
|
476
|
+
private newRow;
|
|
477
|
+
/**
|
|
478
|
+
* Builds the table inside `container`, which should be empty.
|
|
479
|
+
*
|
|
480
|
+
* @throws If a column has an `editor` and there's no `rowId`.
|
|
481
|
+
* @throws If `onDelete` is set and there's no `rowId`.
|
|
482
|
+
* @throws If a hidden column (`visible: false`) has an `editor`.
|
|
483
|
+
* @throws If a select's `labelProp` is its own column.
|
|
484
|
+
*/
|
|
485
|
+
constructor(container: HTMLElement, options: TadabutOptions<Row>);
|
|
486
|
+
/**
|
|
487
|
+
* Replaces all rows. Sorting, search and the page are kept.
|
|
488
|
+
*
|
|
489
|
+
* Open rows, and the new row, are closed first, and their unsaved changes
|
|
490
|
+
* are lost.
|
|
491
|
+
*/
|
|
492
|
+
setData(rows: readonly Row[]): void;
|
|
493
|
+
/**
|
|
494
|
+
* Opens a row for editing.
|
|
495
|
+
*
|
|
496
|
+
* @param id The value of the row's `rowId` field.
|
|
497
|
+
* @returns `false` if the row doesn't exist, is already open, another row
|
|
498
|
+
* or the new row is open in `'single'` mode, nothing is editable, the row
|
|
499
|
+
* is being deleted, or it's on a page that hasn't been displayed yet.
|
|
500
|
+
*/
|
|
501
|
+
edit(id: string | number): boolean;
|
|
502
|
+
/**
|
|
503
|
+
* Opens an empty row at the top of the table, for a new row. `defaults` are
|
|
504
|
+
* its starting values. The row is only added once Save works.
|
|
505
|
+
*
|
|
506
|
+
* @returns `false` if no column has an editor, a new row is already open,
|
|
507
|
+
* or a row is being edited in `'single'` mode.
|
|
508
|
+
*
|
|
509
|
+
* @example
|
|
510
|
+
* table.add({ country: 'MA' });
|
|
511
|
+
*/
|
|
512
|
+
add(defaults?: Partial<Row>): boolean;
|
|
513
|
+
/** Whether a new row is open. */
|
|
514
|
+
isAdding(): boolean;
|
|
515
|
+
/**
|
|
516
|
+
* Closes the new row and throws it away. Does nothing if there's none, or
|
|
517
|
+
* while it's saving.
|
|
518
|
+
*/
|
|
519
|
+
cancelNew(): void;
|
|
520
|
+
/**
|
|
521
|
+
* Validates the new row, then calls `onAdd`. On success the row joins the
|
|
522
|
+
* table, and the table shows the page it landed on.
|
|
523
|
+
*
|
|
524
|
+
* While `onAdd` runs the row is locked. If it throws, the row stays open
|
|
525
|
+
* and the error message is shown under it.
|
|
526
|
+
*
|
|
527
|
+
* @returns `true` once the row is added. `false` if there's no new row, a
|
|
528
|
+
* field is invalid, it's already saving, or `onAdd` threw.
|
|
529
|
+
* @throws If the saved row has no `rowId` value.
|
|
530
|
+
*/
|
|
531
|
+
saveNew(): Promise<boolean>;
|
|
532
|
+
/**
|
|
533
|
+
* Closes a row and throws away its changes. Does nothing if the row isn't
|
|
534
|
+
* open, or while it's saving.
|
|
535
|
+
*/
|
|
536
|
+
cancel(id: string | number): void;
|
|
537
|
+
/** Whether a row is open for editing. */
|
|
538
|
+
isEditing(id: string | number): boolean;
|
|
539
|
+
/**
|
|
540
|
+
* Validates the open row, then calls `onSave`.
|
|
541
|
+
*
|
|
542
|
+
* Invalid fields show their errors and `onSave` isn't called. While
|
|
543
|
+
* `onSave` runs the row is locked. If it throws, the row stays open and
|
|
544
|
+
* the error message is shown under it. The table only changes on success.
|
|
545
|
+
*
|
|
546
|
+
* @returns `true` once the row is saved and closed.
|
|
547
|
+
*/
|
|
548
|
+
save(id: string | number): Promise<boolean>;
|
|
549
|
+
/**
|
|
550
|
+
* Calls `onDelete`, then removes the row. Never asks first: only the
|
|
551
|
+
* Delete button does.
|
|
552
|
+
*
|
|
553
|
+
* While `onDelete` runs the row is locked. If it throws, the row stays and
|
|
554
|
+
* the error message is shown under it.
|
|
555
|
+
*
|
|
556
|
+
* @returns `true` once the row is removed. `false` if the row doesn't
|
|
557
|
+
* exist, is open for editing, is already being deleted, or `onDelete`
|
|
558
|
+
* threw.
|
|
559
|
+
*/
|
|
560
|
+
delete(id: string | number): Promise<boolean>;
|
|
561
|
+
/** Removes the table. Open rows are closed without saving. */
|
|
562
|
+
destroy(): void;
|
|
563
|
+
/** The row with this id, or `undefined`. */
|
|
564
|
+
private findRow;
|
|
565
|
+
/**
|
|
566
|
+
* Closes every open row, the new one too. Only for when the rows are about
|
|
567
|
+
* to go away: cells aren't restored.
|
|
568
|
+
*/
|
|
569
|
+
private destroySessions;
|
|
570
|
+
/** Also works after the session is gone, so a row can always be unlocked. */
|
|
571
|
+
private setSaving;
|
|
572
|
+
/** Shows a save or delete error in a child row under the row. */
|
|
573
|
+
private showRowError;
|
|
574
|
+
/** Removes the save or delete error under a row, if any. */
|
|
575
|
+
private clearRowError;
|
|
576
|
+
/** The last cell of a row, the one with the buttons. */
|
|
577
|
+
private actionsCell;
|
|
578
|
+
/**
|
|
579
|
+
* What the Delete button does: asks inline, asks with the user's function,
|
|
580
|
+
* or deletes right away.
|
|
581
|
+
*/
|
|
582
|
+
private askDelete;
|
|
583
|
+
/** Puts Edit and Delete back after No. */
|
|
584
|
+
private keepRow;
|
|
585
|
+
/** Whether an element is inside the new row, or its error. */
|
|
586
|
+
private isInNewRow;
|
|
587
|
+
/**
|
|
588
|
+
* `undefined` for rows DataTables doesn't know, like the error row or
|
|
589
|
+
* a table inside a custom editor.
|
|
590
|
+
*/
|
|
591
|
+
private rowIdOf;
|
|
592
|
+
/**
|
|
593
|
+
* Handles the action buttons, the new row's too. One listener on the
|
|
594
|
+
* table, because DataTables keeps replacing rows. An arrow function, so
|
|
595
|
+
* `this` stays bound and `destroy` can remove it.
|
|
596
|
+
*/
|
|
597
|
+
private readonly onClick;
|
|
598
|
+
/** Enter saves, Escape cancels, in edited rows and the new row. */
|
|
599
|
+
private readonly onKeyDown;
|
|
600
|
+
}
|
|
601
|
+
/** English, the default. */
|
|
602
|
+
declare const en: Texts;
|
|
603
|
+
/** French. */
|
|
604
|
+
declare const fr: Texts;
|
|
605
|
+
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
|
|
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, type TableClassNames, 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-mZisu7MG.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-DWwW61Yo.js";
|
package/dist/react.d.ts
CHANGED
|
@@ -1,39 +1,20 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { c as TadabutOptions, r as Tadabut$1 } from "./index-mZisu7MG.js";
|
|
2
2
|
import { ReactElement, Ref } from "react";
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
*/
|
|
11
|
-
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
|
-
*/
|
|
3
|
+
/** What the `ref` gets. No `setData`: change the `data` prop instead. */
|
|
4
|
+
export type TadabutHandle<Row extends object> = Pick<Tadabut$1<Row>, "edit" | "save" | "cancel" | "delete" | "isEditing" | "add" | "isAdding" | "saveNew" | "cancelNew">;
|
|
5
|
+
/** The core options, plus `ref`. */
|
|
17
6
|
export type TadabutProps<Row extends object> = TadabutOptions<Row> & {
|
|
18
|
-
/**
|
|
7
|
+
/**
|
|
8
|
+
* Gives you the same methods as the core table: `edit`, `save`, `cancel`,
|
|
9
|
+
* `delete`, `add`, `saveNew`, `cancelNew`, `isEditing` and `isAdding`.
|
|
10
|
+
*/
|
|
19
11
|
readonly ref?: Ref<TadabutHandle<Row>>;
|
|
20
12
|
};
|
|
21
13
|
/**
|
|
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`, `editing.button` or `classNames`
|
|
30
|
-
* values rebuild the table, and any row being edited is lost. Define
|
|
31
|
-
* `columns` outside the component, or with `useMemo`.
|
|
32
|
-
* - `editing` and `classNames` can be new objects on every render: only a
|
|
33
|
-
* change in their values rebuilds the table.
|
|
34
|
-
* - `onSave` can be a new function on every render. The table always calls
|
|
35
|
-
* the latest one, without being rebuilt.
|
|
36
|
-
*
|
|
37
|
-
* @typeParam Row - The shape of one row. Usually worked out from `data`.
|
|
14
|
+
* New `data` updates the table in place. Changing `columns`, `rowId`,
|
|
15
|
+
* `dataTables` or `texts` rebuilds it (and closes open rows), so keep those
|
|
16
|
+
* stable with a constant or `useMemo`. `editing`, `classNames`, `onSave`,
|
|
17
|
+
* `onAdd`, `onDelete` and `confirmDelete` can be inline: they're compared by value or
|
|
18
|
+
* read through a ref.
|
|
38
19
|
*/
|
|
39
|
-
export declare function Tadabut<Row extends object>({ data, columns, rowId, editing, classNames, onSave, ref }: TadabutProps<Row>): ReactElement;
|
|
20
|
+
export declare function Tadabut<Row extends object>({ data, columns, rowId, editing, classNames, dataTables, texts, onSave, onAdd, onDelete, confirmDelete, ref }: TadabutProps<Row>): ReactElement;
|