tadabut 0.5.0 → 0.7.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.
@@ -1,8 +1,13 @@
1
- import { Config } from "datatables.net";
1
+ import { Api, Config } from "datatables.net";
2
2
  /** Options every editor has. */
3
3
  type BaseEditor = {
4
4
  /** Extra classes for the input, like `'form-control'`. */
5
5
  readonly className?: string;
6
+ /**
7
+ * Shows the value in a locked input. The field is never checked, and saving
8
+ * keeps the value as it was. Defaults to `false`.
9
+ */
10
+ readonly readOnly?: boolean;
6
11
  };
7
12
  /** What a custom editor's `create` receives. */
8
13
  type EditorContext<Value> = {
@@ -10,6 +15,8 @@ type EditorContext<Value> = {
10
15
  readonly value: Value;
11
16
  /** The `className` from the editor config. Put it on your element. */
12
17
  readonly className?: string;
18
+ /** Whether the field is locked. With `true`, disable your input. */
19
+ readonly readOnly?: boolean;
13
20
  /** Call it when the user changes the value. */
14
21
  readonly onChange: (value: Value) => void;
15
22
  };
@@ -75,24 +82,91 @@ type CheckboxEditor<Value = boolean> = BaseEditor & {
75
82
  type CustomEditor<Value> = BaseEditor & {
76
83
  /** Picks this editor. */
77
84
  readonly type: "custom";
78
- /** Builds your editor. Runs every time a row opens. */
85
+ /**
86
+ * Builds your editor. Runs every time a row opens. With `readOnly`,
87
+ * `context.readOnly` is `true`: disable your input.
88
+ */
79
89
  readonly create: (context: EditorContext<Value>) => EditorInstance<Value>;
80
90
  };
91
+ /** The separators a date format can use. */
92
+ type DateSeparator = "/" | "-" | ".";
81
93
  /**
82
- * For `string` columns holding `'YYYY-MM-DD'`. Anything else, like
83
- * `'2024-01-05T00:00:00'`, shows as empty and saves as `null`. Empty gives
84
- * `null`.
94
+ * How a date is written: `dd`, `mm` and `yyyy` in any order, with `/`, `-`
95
+ * or `.` between them.
96
+ *
97
+ * @example
98
+ * 'dd/mm/yyyy'
99
+ */
100
+ type DateFormat = { [S in DateSeparator]: `dd${S}mm${S}yyyy` | `mm${S}dd${S}yyyy` | `yyyy${S}mm${S}dd` | `yyyy${S}dd${S}mm` | `dd${S}yyyy${S}mm` | `mm${S}yyyy${S}dd`; }[DateSeparator];
101
+ /** ISO, what `<input type="date">` and most servers use. */
102
+ declare const defaultDateFormat: DateFormat;
103
+ /**
104
+ * Reads a date written in `format`, and gives it as `'yyyy-mm-dd'`. A time
105
+ * after it is dropped. `null` if it isn't a real date, like `31/02/2024`.
106
+ *
107
+ * @example
108
+ * parseDate('05/01/2024', 'dd/mm/yyyy'); // '2024-01-05'
109
+ */
110
+ declare function parseDate(value: string, format: DateFormat): string | null;
111
+ /**
112
+ * Writes a `'yyyy-mm-dd'` date in `format`. Only give it dates `parseDate`
113
+ * returned: it checks nothing.
114
+ *
115
+ * @example
116
+ * formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
117
+ */
118
+ declare function formatDate(iso: string, format: DateFormat): string;
119
+ /**
120
+ * For `string` columns holding a date written in `format`. A time after the
121
+ * date is dropped. Anything else shows as empty and saves as `null`. Empty
122
+ * gives `null`.
85
123
  *
86
124
  * @example
87
- * { type: 'date', min: '2020-01-01', max: '2030-12-31' }
125
+ * { type: 'date', format: 'dd/mm/yyyy', min: '01/01/2020' }
88
126
  */
89
127
  type DateEditor = BaseEditor & {
90
128
  /** Picks this editor. */
91
129
  readonly type: "date";
92
- /** Earliest date, as `'YYYY-MM-DD'`. */
130
+ /** Earliest date, written in `format`. */
93
131
  readonly min?: string;
94
- /** Latest date, as `'YYYY-MM-DD'`. */
132
+ /** Latest date, written in `format`. */
95
133
  readonly max?: string;
134
+ /**
135
+ * How the date is written in your rows: what the server sends and what
136
+ * `onSave` gets. Defaults to `'yyyy-mm-dd'`.
137
+ */
138
+ readonly format?: DateFormat;
139
+ /** How the cell shows it. Defaults to `format`. */
140
+ readonly display?: DateFormat;
141
+ };
142
+ /**
143
+ * For `string` columns holding a date and a time: the date in `format`, then
144
+ * the time, like `'05/01/2024 14:30'`. With the default ISO format, a `T`
145
+ * goes between them: `'2024-01-05T14:30'`.
146
+ *
147
+ * When reading, a `T` or a space both work, a date alone counts as midnight,
148
+ * and what comes after the seconds (`.000Z`) is ignored: the time is shown as
149
+ * written, not converted. Anything else shows as empty and saves as `null`.
150
+ *
151
+ * @example
152
+ * { type: 'datetime', format: 'dd/mm/yyyy', min: '01/01/2020 08:00' }
153
+ */
154
+ type DateTimeEditor = BaseEditor & {
155
+ /** Picks this editor. */
156
+ readonly type: "datetime";
157
+ /**
158
+ * How the date part is written in your rows. Defaults to `'yyyy-mm-dd'`.
159
+ * The time always follows, as `hh:mm`.
160
+ */
161
+ readonly format?: DateFormat;
162
+ /** How the cell shows the date part. Defaults to `format`. */
163
+ readonly display?: DateFormat;
164
+ /** Earliest date and time, written like the data: `'01/01/2020 08:00'`. */
165
+ readonly min?: string;
166
+ /** Latest date and time, written like the data. */
167
+ readonly max?: string;
168
+ /** Shows and saves the seconds. Defaults to `false`. */
169
+ readonly seconds?: boolean;
96
170
  };
97
171
  /** How a money input and its cells look. */
98
172
  type MoneyFormat = {
@@ -172,6 +246,10 @@ type Texts = {
172
246
  readonly deleteFailed: string;
173
247
  /** In the footer's first cell, when that column has no total of its own. */
174
248
  readonly total: string;
249
+ /** The label of each row's checkbox, for screen readers. */
250
+ readonly selectRow: string;
251
+ /** The label of the header checkbox. */
252
+ readonly selectAll: string;
175
253
  /** Shown in a select while its options load. */
176
254
  readonly loading: string;
177
255
  /** Under a row when `onSave` throws something that isn't an `Error`. */
@@ -184,6 +262,14 @@ type Texts = {
184
262
  readonly required: string;
185
263
  /** A text that doesn't match `pattern`. */
186
264
  readonly patternMismatch: string;
265
+ /** The label of the ▸ button, for screen readers. */
266
+ readonly showDetail: string;
267
+ /** Its label while the detail is open. */
268
+ readonly hideDetail: string;
269
+ /** Shown while an async `detail` loads. */
270
+ readonly detailLoading: string;
271
+ /** Shown when `detail` throws something that isn't an `Error`. */
272
+ readonly detailFailed: string;
187
273
  /** A text shorter than `minLength`. */
188
274
  readonly tooShort: (min: number) => string;
189
275
  /** A text longer than `maxLength`. */
@@ -192,10 +278,14 @@ type Texts = {
192
278
  readonly tooSmall: (min: number) => string;
193
279
  /** A number above `max`. */
194
280
  readonly tooLarge: (max: number) => string;
195
- /** A date before `min`, given as `'YYYY-MM-DD'`. */
281
+ /** A date before `min`, given as the column shows dates (its `display`). */
196
282
  readonly tooEarly: (min: string) => string;
197
- /** A date after `max`, given as `'YYYY-MM-DD'`. */
283
+ /** A date after `max`, given as the column shows dates (its `display`). */
198
284
  readonly tooLate: (max: string) => string;
285
+ /** A time before `min`, like `'08:00'`. */
286
+ readonly timeTooEarly: (min: string) => string;
287
+ /** A time after `max`, like `'18:00'`. */
288
+ readonly timeTooLate: (max: string) => string;
199
289
  };
200
290
  /** One choice in a select. */
201
291
  type SelectOption<Value> = {
@@ -269,21 +359,38 @@ type TextEditor = BaseEditor & {
269
359
  /** Must match the whole value, like `'[A-Z]{2}[0-9]{4}'`. No slashes, no `^`/`$`. */
270
360
  readonly pattern?: string;
271
361
  };
362
+ /**
363
+ * For `string` columns holding a time, like `'14:30'`. Anything that isn't a
364
+ * time shows as empty and saves as `null`. Empty gives `null`.
365
+ *
366
+ * @example
367
+ * { type: 'time', min: '08:00', max: '18:00' }
368
+ */
369
+ type TimeEditor = BaseEditor & {
370
+ /** Picks this editor. */
371
+ readonly type: "time";
372
+ /** Earliest time, like `'08:00'`. */
373
+ readonly min?: string;
374
+ /** Latest time, like `'18:00'`. */
375
+ readonly max?: string;
376
+ /** Shows and saves the seconds: `'14:30:00'` instead of `'14:30'`. Defaults to `false`. */
377
+ readonly seconds?: boolean;
378
+ };
272
379
  /**
273
380
  * Which editors a column can have, from its value type:
274
381
  *
275
- * | Column value | Built-in editors |
276
- * | ------------- | --------------------------------------------- |
277
- * | `string` | text, date, select, checkbox with `values` |
278
- * | `number` | number, money, select, checkbox with `values` |
279
- * | `boolean` | checkbox, select |
382
+ * | Column value | Built-in editors |
383
+ * | ------------- | ------------------------------------------------------------- |
384
+ * | `string` | text, date, time, datetime, select, checkbox with `values` |
385
+ * | `number` | number, money, select, checkbox with `values` |
386
+ * | `boolean` | checkbox, select |
280
387
  *
281
388
  * `custom` works on anything. Nullable columns get the same editors as
282
389
  * non-nullable ones.
283
390
  */
284
391
  type EditorFor<Value, Row> = EditorForValue<NonNullable<Value>, Row> | CustomEditor<Value>;
285
392
  /** The built-in editors for a non-null value type. */
286
- type EditorForValue<Value, Row> = [Value] extends [string] ? TextEditor | DateEditor | SelectEditor<Value, Row> | CheckboxEditor<Value> : [Value] extends [number] ? NumberEditor | MoneyEditor | SelectEditor<Value, Row> | CheckboxEditor<Value> : [Value] extends [boolean] ? CheckboxEditor | SelectEditor<Value, Row> : never;
393
+ type EditorForValue<Value, Row> = [Value] extends [string] ? TextEditor | DateEditor | TimeEditor | DateTimeEditor | SelectEditor<Value, Row> | CheckboxEditor<Value> : [Value] extends [number] ? NumberEditor | MoneyEditor | SelectEditor<Value, Row> | CheckboxEditor<Value> : [Value] extends [boolean] ? CheckboxEditor | SelectEditor<Value, Row> : never;
287
394
  /**
288
395
  * Works on every editor. An empty value fails `required` and skips every
289
396
  * other check. Otherwise the editor's own rules (`min`, `maxLength`…) run,
@@ -325,8 +432,6 @@ type TotalFunction<Row extends object> = (rows: readonly Row[]) => string;
325
432
  * number columns. `count` and a function work everywhere.
326
433
  */
327
434
  type TotalFor<Value, Row extends object> = [NonNullable<Value>] extends [number] ? NumberTotal | "count" | TotalFunction<Row> : "count" | TotalFunction<Row>;
328
- /** Which rows the totals count. */
329
- type TotalRows = "searched" | "all" | "page";
330
435
  /**
331
436
  * A table column. The `editor` has to fit the type of `prop`, so a number
332
437
  * field can't get a text input. Columns without an editor are read-only.
@@ -374,6 +479,43 @@ type ColumnFor<Row extends object, Key extends keyof Row & string> = {
374
479
  /** Classes for the cells (header too), not for the input. */
375
480
  readonly className?: string;
376
481
  };
482
+ /**
483
+ * Reads a date in `format`, then a time after a `T` or a space, and gives
484
+ * `'yyyy-mm-ddThh:mm:ss'`. No time means midnight. A time zone is ignored,
485
+ * not converted. `null` if the date or the time isn't real.
486
+ *
487
+ * @example
488
+ * parseDateTime('05/01/2024 14:30', 'dd/mm/yyyy'); // '2024-01-05T14:30:00'
489
+ */
490
+ declare function parseDateTime(value: string, format: DateFormat): string | null;
491
+ /**
492
+ * Writes a date-time `parseDateTime` returned. `separator` goes between the
493
+ * date and the time.
494
+ *
495
+ * @example
496
+ * formatDateTime('2024-01-05T14:30:00', 'dd/mm/yyyy', false, ' '); // '05/01/2024 14:30'
497
+ */
498
+ declare function formatDateTime(value: string, format: DateFormat, seconds: boolean, separator: string): string;
499
+ /**
500
+ * Reads `'h:mm'`, `'hh:mm'` or `'hh:mm:ss'`, and gives `'hh:mm:ss'`. Anything
501
+ * after is ignored, like `'.000Z'`. `null` if it isn't a real time.
502
+ *
503
+ * @example
504
+ * parseTime('9:05'); // '09:05:00'
505
+ */
506
+ declare function parseTime(value: string): string | null;
507
+ /**
508
+ * Writes a time `parseTime` returned, with or without the seconds.
509
+ *
510
+ * @example
511
+ * formatTime('09:05:00', false); // '09:05'
512
+ */
513
+ declare function formatTime(time: string, seconds: boolean): string;
514
+ /**
515
+ * Which rows something counts: every row matching the search (on every
516
+ * page), every row, or the rows on the page shown.
517
+ */
518
+ type RowScope = "searched" | "all" | "page";
377
519
  /** The second argument of `onSave`. */
378
520
  type SaveContext<Row extends object> = {
379
521
  /** The row as it was before editing. */
@@ -392,6 +534,11 @@ type EditingOptions = {
392
534
  * shows if `onDelete` is set.
393
535
  */
394
536
  readonly button?: boolean;
537
+ /**
538
+ * Double-clicking a row opens it for editing. Defaults to `false`.
539
+ * `onRowDoubleClick` still fires.
540
+ */
541
+ readonly doubleClick?: boolean;
395
542
  };
396
543
  /**
397
544
  * Extra CSS classes for the table and its buttons. They're added next to the
@@ -408,6 +555,7 @@ type EditingOptions = {
408
555
  * delete: 'btn-outline-danger',
409
556
  * confirm: 'btn-danger',
410
557
  * keep: 'btn-outline-secondary',
558
+ * select: 'form-check-input',
411
559
  * }
412
560
  */
413
561
  type TableClassNames = {
@@ -427,6 +575,10 @@ type TableClassNames = {
427
575
  readonly confirm?: string;
428
576
  /** The button that keeps the row instead. */
429
577
  readonly keep?: string;
578
+ /** The selection checkboxes, header included. */
579
+ readonly select?: string;
580
+ /** The button that opens and closes a detail. */
581
+ readonly detail?: string;
430
582
  };
431
583
  /**
432
584
  * Any {@link https://datatables.net/reference/option/ | DataTables option},
@@ -438,6 +590,21 @@ type TableClassNames = {
438
590
  * { order: [[1, 'asc']], pageLength: 20, language: { search: 'Rechercher :' } }
439
591
  */
440
592
  type DataTablesSettings = Omit<Config, "data" | "columns" | "columnDefs" | "ajax" | "serverSide">;
593
+ /** Options for `selection`. */
594
+ type SelectionOptions = {
595
+ /**
596
+ * Which rows the header checkbox selects. Defaults to `'searched'`: every
597
+ * row that matches the search, on every page.
598
+ */
599
+ readonly checkAll?: RowScope;
600
+ };
601
+ /** What `detail` returns: an element, or text. Text is shown as it is, never as HTML. */
602
+ type DetailContent = Node | string;
603
+ /** The second argument of `detail`. */
604
+ type DetailContext = {
605
+ /** Aborted when the detail closes before it finished loading. Pass it to `fetch`. */
606
+ readonly signal: AbortSignal;
607
+ };
441
608
  /** Options for `new Tadabut()`. */
442
609
  type TadabutOptions<Row extends object> = {
443
610
  /** The rows. The array is copied, never changed. */
@@ -469,7 +636,37 @@ type TadabutOptions<Row extends object> = {
469
636
  *
470
637
  * Does nothing unless a column has `total`.
471
638
  */
472
- readonly totalRows?: TotalRows;
639
+ readonly totalRows?: RowScope;
640
+ /**
641
+ * Adds a first column with a checkbox on each row, and one in the header to
642
+ * check them all. `true` uses the defaults. Needs `rowId`.
643
+ *
644
+ * @example
645
+ * selection: { checkAll: 'page' }
646
+ */
647
+ readonly selection?: boolean | SelectionOptions;
648
+ /**
649
+ * Called with the selected rows each time the selection changes, by a
650
+ * click or from code.
651
+ */
652
+ readonly onSelect?: (rows: readonly Row[]) => void;
653
+ /**
654
+ * Adds a ▸ button at the start of each row. It opens a line under the row
655
+ * with what this returns. May be async: "Loading…" shows while it waits,
656
+ * and the error message if it throws. It runs again after the row is
657
+ * saved. Needs `rowId`.
658
+ *
659
+ * @example
660
+ * detail: async (row, { signal }) => {
661
+ * const res = await fetch(`/api/orders/${row.id}/lines`, { signal });
662
+ * const box = document.createElement('ul');
663
+ * for (const line of await res.json()) {
664
+ * box.append(Object.assign(document.createElement('li'), { textContent: line.label }));
665
+ * }
666
+ * return box;
667
+ * }
668
+ */
669
+ readonly detail?: (row: Row, context: DetailContext) => DetailContent | Promise<DetailContent>;
473
670
  /**
474
671
  * Called with the edited row once it passes validation. May be async.
475
672
  *
@@ -515,6 +712,37 @@ type TadabutOptions<Row extends object> = {
515
712
  * confirmDelete: (row) => window.confirm(`Delete ${row.name}?`)
516
713
  */
517
714
  readonly confirmDelete?: false | ((row: Row) => boolean | Promise<boolean>);
715
+ /**
716
+ * Called when a row opens for editing: by the Edit button, a double click,
717
+ * or `edit()`. Return `false` to keep it closed; `edit()` then returns
718
+ * `false`. Not called for the new row `add()` opens.
719
+ *
720
+ * @example
721
+ * onEditStart: (row) => row.status !== 'validated'
722
+ */
723
+ readonly onEditStart?: (row: Row) => boolean | void;
724
+ /**
725
+ * Called after a save worked and the row closed, with the row as it is now
726
+ * in the table (what `onSave` returned, if anything) and the row before
727
+ * editing.
728
+ */
729
+ readonly onSaved?: (row: Row, context: SaveContext<Row>) => void;
730
+ /** Called after a new row joined the table, with the row as saved. */
731
+ readonly onAdded?: (row: Row) => void;
732
+ /** Called after a row left the table, with that row. */
733
+ readonly onDeleted?: (row: Row) => void;
734
+ /**
735
+ * Called when a row is clicked. Clicks on buttons, inputs and checkboxes
736
+ * don't count, and neither do clicks in a row being edited, the new row,
737
+ * or an error line.
738
+ */
739
+ readonly onRowClick?: (row: Row, event: MouseEvent) => void;
740
+ /**
741
+ * Called when a row is double-clicked, with the same rules as
742
+ * `onRowClick`. The browser fires two clicks first, so `onRowClick` runs
743
+ * twice before it.
744
+ */
745
+ readonly onRowDoubleClick?: (row: Row, event: MouseEvent) => void;
518
746
  };
519
747
  /**
520
748
  * A DataTables table with row editing.
@@ -537,7 +765,7 @@ declare class Tadabut<Row extends object> {
537
765
  /** The `<table>` Tadabut created. */
538
766
  private readonly tableEl;
539
767
  /** The field that identifies a row. */
540
- private readonly rowId;
768
+ private readonly rowId?;
541
769
  /** The user's columns, without the actions column. */
542
770
  private readonly columns;
543
771
  /** `editing` with its defaults filled in. */
@@ -563,35 +791,134 @@ declare class Tadabut<Row extends object> {
563
791
  /** Rows waiting for `onDelete`, by row id. */
564
792
  private readonly deleting;
565
793
  /** The row `add()` opened, if any. */
566
- private newRow;
794
+ private newRow?;
567
795
  /** Whether any column has a `total`, so the table has a footer. */
568
796
  private readonly hasTotals;
569
797
  /** Which rows the totals count, with its default filled in. */
570
798
  private readonly totalRows;
799
+ /** How many columns Tadabut adds before yours: the checkboxes and the ▸ button. */
800
+ private readonly offset;
801
+ /** The ticked rows. Only with `selection`. */
802
+ private readonly selection?;
803
+ /** Asked before a row opens. */
804
+ private readonly onEditStart;
805
+ /** The user's after-save callback. */
806
+ private readonly onSaved;
807
+ /** The user's after-add callback. */
808
+ private readonly onAdded;
809
+ /** The user's after-delete callback. */
810
+ private readonly onDeleted;
811
+ /** The user's row click callback. */
812
+ private readonly onRowClick;
813
+ /** The user's row double click callback. */
814
+ private readonly onRowDoubleClick;
815
+ /** The lines under each row: details and errors. */
816
+ private readonly rowLines;
817
+ /** The last options each select loaded, by field. */
818
+ private readonly loadedOptions;
571
819
  /**
572
820
  * Builds the table inside `container`, which should be empty.
573
821
  *
574
822
  * @throws If a column has an `editor` and there's no `rowId`.
575
823
  * @throws If `onDelete` is set and there's no `rowId`.
824
+ * @throws If `selection` is on and there's no `rowId`.
825
+ * @throws If `detail` is set and there's no `rowId`.
576
826
  * @throws If a hidden column (`visible: false`) has an `editor`.
577
827
  * @throws If a select's `labelProp` is its own column.
578
828
  * @throws If a money editor's `separator` and `point` are the same.
829
+ * @throws If a date editor's `min` or `max` isn't a real date in its `format`.
830
+ * @throws If a time editor's `min` or `max` isn't a real time.
831
+ * @throws If a datetime editor's `min` or `max` isn't a real date and time in its `format`.
579
832
  */
580
833
  constructor(container: HTMLElement, options: TadabutOptions<Row>);
581
834
  /**
582
835
  * Replaces all rows. Sorting, search and the page are kept.
583
836
  *
584
837
  * Open rows, and the new row, are closed first, and their unsaved changes
585
- * are lost.
838
+ * are lost. Open details close too.
586
839
  */
587
840
  setData(rows: readonly Row[]): void;
841
+ /**
842
+ * Every row, in the order shown. `scope` works like `totalRows`: `'all'`
843
+ * (default), `'searched'` or `'page'`. They're copies, so changing them
844
+ * changes nothing: use `updateRow` for that.
845
+ *
846
+ * @example
847
+ * table.getData('searched'); // the rows that match the search
848
+ */
849
+ getData(scope?: RowScope): Row[];
850
+ /**
851
+ * The row with this id, as a copy, or `undefined`. It's the saved row:
852
+ * while a row is edited, what's typed isn't in it until Save.
853
+ */
854
+ getRow(id: string | number): Row | undefined;
855
+ /**
856
+ * The DataTables API, for anything Tadabut doesn't do itself.
857
+ *
858
+ * Careful: rows added or removed through it skip Tadabut, so the
859
+ * selection, details and open rows won't know. Use `insertRow`,
860
+ * `updateRow`, `removeRow` and `setData` for that.
861
+ *
862
+ * @example
863
+ * table.getApi().order([2, 'desc']).draw();
864
+ */
865
+ getApi(): Api<Row>;
866
+ /**
867
+ * Puts one row or many in the table, without `onAdd` or the new-row form,
868
+ * and `onAdded` doesn't fire. They go where the sorting puts them, and the
869
+ * table stays on the page it's on. Either every row goes in, or none.
870
+ *
871
+ * @throws If there's no `rowId`, a row has no `rowId` value, or its id is
872
+ * already in the table (or twice in `rows`).
873
+ *
874
+ * @example
875
+ * table.insertRow(rowFromServer);
876
+ */
877
+ insertRow(rows: Row | readonly Row[]): void;
878
+ /**
879
+ * Replaces the row with the same id, without `onSave`, and `onSaved` doesn't
880
+ * fire. An open detail reloads.
881
+ *
882
+ * @returns `false` if no row has this id, or it's being edited or deleted.
883
+ *
884
+ * @example
885
+ * table.updateRow({ ...table.getRow(1), name: 'Nadia' });
886
+ */
887
+ updateRow(row: Row): boolean;
888
+ /**
889
+ * Takes a row out of the table, without `onDelete` and without asking, and
890
+ * `onDeleted` doesn't fire. Its detail closes, and it leaves the selection.
891
+ *
892
+ * @returns `false` if no row has this id, or it's being edited or deleted.
893
+ */
894
+ removeRow(id: string | number): boolean;
895
+ /**
896
+ * The footer's totals, by field: numbers for built-in totals (not
897
+ * formatted, rounded like the footer), or your function's text. They count
898
+ * the same rows as the footer. If two columns show the same field with a
899
+ * total each, the last one wins.
900
+ *
901
+ * @example
902
+ * table.getTotals().salary; // 176651.5
903
+ */
904
+ getTotals(): Partial<Record<keyof Row & string, number | string>>;
905
+ /**
906
+ * A select's options. With a fixed list, that list. With an `options`
907
+ * function, the list it last loaded in an open row, or `undefined` before
908
+ * any row was opened. `undefined` for a column that isn't a select.
909
+ *
910
+ * @example
911
+ * table.getOptions('countryId'); // [{ value: 1, label: 'Morocco' }, …]
912
+ */
913
+ getOptions<Key extends keyof Row & string>(prop: Key): readonly SelectOption<NonNullable<Row[Key]>>[] | undefined;
588
914
  /**
589
915
  * Opens a row for editing.
590
916
  *
591
917
  * @param id The value of the row's `rowId` field.
592
918
  * @returns `false` if the row doesn't exist, is already open, another row
593
919
  * or the new row is open in `'single'` mode, nothing is editable, the row
594
- * is being deleted, or it's on a page that hasn't been displayed yet.
920
+ * is being deleted, it's on a page that hasn't been displayed yet, or
921
+ * `onEditStart` returned `false`.
595
922
  */
596
923
  edit(id: string | number): boolean;
597
924
  /**
@@ -607,6 +934,40 @@ declare class Tadabut<Row extends object> {
607
934
  add(defaults?: Partial<Row>): boolean;
608
935
  /** Whether a new row is open. */
609
936
  isAdding(): boolean;
937
+ /**
938
+ * The selected rows, in the order they were added. Rows the search hides,
939
+ * or on other pages, are in it too. Always `[]` without `selection`.
940
+ */
941
+ getSelected(): Row[];
942
+ /** Whether a row is selected. Always `false` without `selection`. */
943
+ isSelected(id: string | number): boolean;
944
+ /**
945
+ * Selects rows by id. Ids not in the table are skipped. Does nothing
946
+ * without `selection`.
947
+ *
948
+ * @example
949
+ * table.select([1, 2]);
950
+ */
951
+ select(ids: readonly (string | number)[]): void;
952
+ /** Unselects rows by id. Does nothing without `selection`. */
953
+ deselect(ids: readonly (string | number)[]): void;
954
+ /** Unselects every row. Does nothing without `selection`. */
955
+ clearSelection(): void;
956
+ /**
957
+ * Opens a row's detail under it. "Loading…" shows until `detail` returns.
958
+ * Does nothing without `detail`, if it's open already, or if the row
959
+ * isn't in the table.
960
+ *
961
+ * @example
962
+ * onRowClick: (row) => table.toggleDetail(row.id)
963
+ */
964
+ openDetail(id: string | number): void;
965
+ /** Closes a row's detail, and stops its load if it's still running. Does nothing without `detail`. */
966
+ closeDetail(id: string | number): void;
967
+ /** Opens a closed detail, closes an open one, like the ▸ button. Does nothing without `detail`. */
968
+ toggleDetail(id: string | number): void;
969
+ /** Whether a row's detail is open, or loading. Always `false` without `detail`. */
970
+ isDetailOpen(id: string | number): boolean;
610
971
  /**
611
972
  * Closes the new row and throws it away. Does nothing if there's none, or
612
973
  * while it's saving.
@@ -664,10 +1025,6 @@ declare class Tadabut<Row extends object> {
664
1025
  private destroySessions;
665
1026
  /** Also works after the session is gone, so a row can always be unlocked. */
666
1027
  private setSaving;
667
- /** Shows a save or delete error in a child row under the row. */
668
- private showRowError;
669
- /** Removes the save or delete error under a row, if any. */
670
- private clearRowError;
671
1028
  /** The last cell of a row, the one with the buttons. */
672
1029
  private actionsCell;
673
1030
  /**
@@ -680,8 +1037,9 @@ declare class Tadabut<Row extends object> {
680
1037
  /** Whether an element is inside the new row, or its error. */
681
1038
  private isInNewRow;
682
1039
  /**
683
- * `undefined` for rows DataTables doesn't know, like the error row or
684
- * a table inside a custom editor.
1040
+ * `undefined` for rows DataTables doesn't know, like a table inside a custom
1041
+ * editor, and for the lines under a row (detail and error), which DataTables
1042
+ * maps back to their row.
685
1043
  */
686
1044
  private rowIdOf;
687
1045
  /**
@@ -697,9 +1055,24 @@ declare class Tadabut<Row extends object> {
697
1055
  * delete and `setData` all redraw.
698
1056
  */
699
1057
  private readonly updateTotals;
1058
+ /** Keeps the options a select loaded, for `getOptions`. An arrow function, so it can be passed as is. */
1059
+ private readonly rememberOptions;
1060
+ /** Your column's index as DataTables counts it. */
1061
+ private dtIndex;
1062
+ /**
1063
+ * The row a click landed on, or `undefined` if it doesn't count: buttons,
1064
+ * inputs, links, the checkbox, ▸ and buttons cells, the new row, a row
1065
+ * being edited, the header, the footer, and the lines under a row.
1066
+ */
1067
+ private clickedRow;
1068
+ /**
1069
+ * Row clicks and double clicks. A double click also opens the row with
1070
+ * `editing.doubleClick`. An arrow function, so `destroy` can remove it.
1071
+ */
1072
+ private readonly onRowEvent;
700
1073
  }
701
1074
  /** English, the default. */
702
1075
  declare const en: Texts;
703
1076
  /** French. */
704
1077
  declare const fr: Texts;
705
- export { defaultMoneyFormat as C, CheckboxEditor as D, CustomEditor as E, EditorContext as O, MoneyFormat as S, DateEditor as T, SelectOption as _, EditingOptions as a, NumberEditor as b, TadabutOptions as c, TotalRows as d, ValidationOptions as f, SelectEditor as g, OptionsContext as h, DataTablesSettings as i, EditorInstance as k, Column as l, TextEditor as m, en as n, SaveContext as o, EditorFor as p, Tadabut as r, TableClassNames as s, fr as t, TotalFunction as u, SelectOptionsLoader as v, formatMoney as w, MoneyEditor as x, Texts as y };
1078
+ export { MoneyFormat as A, CheckboxEditor as B, OptionsContext as C, Texts as D, SelectOptionsLoader as E, DateFormat as F, EditorInstance as H, defaultDateFormat as I, formatDate as L, formatMoney as M, DateTimeEditor as N, NumberEditor as O, DateEditor as P, parseDate as R, TextEditor as S, SelectOption as T, EditorContext as V, Column as _, DetailContent as a, EditorFor as b, SaveContext as c, TadabutOptions as d, RowScope as f, parseDateTime as g, formatDateTime as h, DataTablesSettings as i, defaultMoneyFormat as j, MoneyEditor as k, SelectionOptions as l, parseTime as m, en as n, DetailContext as o, formatTime as p, Tadabut as r, EditingOptions as s, fr as t, TableClassNames as u, TotalFunction as v, SelectEditor as w, TimeEditor as x, ValidationOptions as y, CustomEditor as z };
package/dist/index.d.ts CHANGED
@@ -1,2 +1,8 @@
1
- import { C as defaultMoneyFormat, D as CheckboxEditor, E as CustomEditor, O as EditorContext, S as MoneyFormat, T as DateEditor, _ as SelectOption, a as EditingOptions, b as NumberEditor, c as TadabutOptions, d as TotalRows, f as ValidationOptions, g as SelectEditor, h as OptionsContext, i as DataTablesSettings, k as EditorInstance, l as Column, m as TextEditor, n as en, o as SaveContext, p as EditorFor, r as Tadabut, s as TableClassNames, t as fr, u as TotalFunction, v as SelectOptionsLoader, w as formatMoney, x as MoneyEditor, y as Texts } from "./index-KmSXRJlI.js";
2
- export { type CheckboxEditor, type Column, type CustomEditor, type DataTablesSettings, type DateEditor, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type MoneyEditor, type MoneyFormat, type NumberEditor, type OptionsContext, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, type TableClassNames, Tadabut, type TadabutOptions, type TextEditor, type Texts, type TotalFunction, type TotalRows, type ValidationOptions, defaultMoneyFormat, en, formatMoney, fr };
1
+ /**
2
+ * Editable, typed DataTables. The React component lives in `tadabut/react`.
3
+ *
4
+ * @packageDocumentation
5
+ * @module tadabut
6
+ */
7
+ import { A as MoneyFormat, B as CheckboxEditor, C as OptionsContext, D as Texts, E as SelectOptionsLoader, F as DateFormat, H as EditorInstance, I as defaultDateFormat, L as formatDate, M as formatMoney, N as DateTimeEditor, O as NumberEditor, P as DateEditor, R as parseDate, S as TextEditor, T as SelectOption, V as EditorContext, _ as Column, a as DetailContent, b as EditorFor, c as SaveContext, d as TadabutOptions, f as RowScope, g as parseDateTime, h as formatDateTime, i as DataTablesSettings, j as defaultMoneyFormat, k as MoneyEditor, l as SelectionOptions, m as parseTime, n as en, o as DetailContext, p as formatTime, r as Tadabut, s as EditingOptions, t as fr, u as TableClassNames, v as TotalFunction, w as SelectEditor, x as TimeEditor, y as ValidationOptions, z as CustomEditor } from "./index-Cm0OsNb6.js";
8
+ export { type CheckboxEditor, type Column, type CustomEditor, type DataTablesSettings, type DateEditor, type DateFormat, type DateTimeEditor, type DetailContent, type DetailContext, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type MoneyEditor, type MoneyFormat, type NumberEditor, type OptionsContext, type RowScope, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, type SelectionOptions, type TableClassNames, Tadabut, type TadabutOptions, type TextEditor, type Texts, type TimeEditor, type TotalFunction, type ValidationOptions, defaultDateFormat, defaultMoneyFormat, en, formatDate, formatDateTime, formatMoney, formatTime, fr, parseDate, parseDateTime, parseTime };
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { n as Tadabut, i as defaultMoneyFormat, r as en, a as formatMoney, t as fr } from "./src-CBK3xu9-.js";
1
+ export { n as Tadabut, u as defaultDateFormat, i as defaultMoneyFormat, r as en, d as formatDate, o as formatDateTime, a as formatMoney, c as formatTime, t as fr, f as parseDate, s as parseDateTime, l as parseTime } from "./src-D6zL6H0B.js";