easy-mat-ui 1.0.1 → 1.1.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 CHANGED
@@ -32,6 +32,10 @@ a configurable **create / edit / view dialog** and a **multi-select** control, w
32
32
  - **Column filters** under the titles (a compact text input or a multi-select per column), global search, sorting,
33
33
  pagination, sticky columns and a header that stays pinned while the rows scroll.
34
34
  - Expandable rows with **child tables**, or several child tables in **tabs** (`childConfig`).
35
+ - **Row grouping** by a column with collapsible groups and *Expand all* / *Collapse all*, **checkbox columns**, and
36
+ group checkboxes that are checked, unchecked or indeterminate (`groupBy`, `ColumnType.Checkbox`).
37
+ - `lib-easy-file-upload`: a button, a drop area or both, with validation and CSV parsing into a table.
38
+ - A configurable toolbar: search, add, save state, import, export and a custom action.
35
39
  - `EasyDialogService`: a configurable dialog to create, edit or view a record.
36
40
  - `lib-easy-multi-select`: a searchable multi-select with select-all, clear, read-only and compact modes, or a single-choice dropdown (`single`).
37
41
  - Reusable interface components, each with `@Input()` / `@Output()` and a typed model: `lib-easy-segmented`,
@@ -44,13 +48,17 @@ a configurable **create / edit / view dialog** and a **multi-select** control, w
44
48
 
45
49
  ## Screenshots
46
50
 
47
- Taken from the [live demo](https://easy-mat-ui.web.app/) (version 20.0.6), not mocked up.
51
+ Taken from the [live demo](https://easy-mat-ui.web.app/) (version 1.1.0), not mocked up.
48
52
 
49
53
  | Light | Dark |
50
54
  |---|---|
51
55
  | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/table-light.png" alt="A cities table in light mode: typed columns, flags, header filters, search and row actions"> | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/table-dark.png" alt="The same table in dark mode"> |
52
56
  | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/dialog-light.png" alt="The edit dialog, built from the same column definitions as the table"> | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/page-builder-light.png" alt="The page builder, which generates a page from the components you choose"> |
53
57
 
58
+ | Grouping and selection | File upload |
59
+ |---|---|
60
+ | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/grouping-dark.png" alt="Countries grouped by continent with checkbox columns and an indeterminate group"> | <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/upload-dark.png" alt="The file upload component as a drop area with a button, a button, and a drop area"> |
61
+
54
62
  ## Requirements and supported versions
55
63
 
56
64
  `easy-mat-ui` supports **Angular 20, 21 and 22** with the same code. The
@@ -188,6 +196,117 @@ dialog.open({
188
196
  }).afterClosed().subscribe(result => console.log(result?.event, result?.data));
189
197
  ```
190
198
 
199
+ ## Grouping, checkboxes and selection
200
+
201
+ Group the rows by a column, with a header per group that can be collapsed. Add a checkbox column to select rows, and
202
+ give the group header a checkbox that selects or clears the whole group.
203
+
204
+ ```typescript
205
+ import { ColumnType, EasyTableConfig, MatColumnTyped } from 'easy-mat-ui';
206
+
207
+ const config = new EasyTableConfig({
208
+ data: countries,
209
+ displayedColumns: [
210
+ new MatColumnTyped({
211
+ name: 'selected',
212
+ type: ColumnType.Checkbox,
213
+ selection: { enabled: true, headerAlign: 'center', disabledFn: (row) => row.locked }
214
+ }),
215
+ new MatColumnTyped({ name: 'continent' }),
216
+ new MatColumnTyped({ name: 'name' })
217
+ ],
218
+ groupBy: {
219
+ field: 'continent',
220
+ collapsible: true,
221
+ expanded: false,
222
+ selectionField: 'selected',
223
+ showToggleAll: true
224
+ }
225
+ });
226
+ ```
227
+
228
+ ```html
229
+ <lib-easy-table
230
+ [config]="config"
231
+ (selectionChange)="onRow($event)"
232
+ (groupSelectionChange)="onGroup($event)" />
233
+ ```
234
+
235
+ | Option | Effect |
236
+ |---|---|
237
+ | `groupBy.field` | The property the rows are grouped by. |
238
+ | `groupBy.collapsible` / `groupBy.expanded` | Whether a group can be collapsed, and whether groups start open. |
239
+ | `groupBy.showToggleAll` | Shows the *Expand all* / *Collapse all* controls (`expandAllLabel` and `collapseAllLabel` are translation keys). |
240
+ | `groupBy.selectionField` | The checkbox column that the group checkbox drives. A group is checked, unchecked or indeterminate depending on its rows. |
241
+ | `groupBy.showGroupColumn` | Keeps the grouping column visible (it is hidden by default). |
242
+ | `groupBy.emptyLabel` | Title of the group of rows that have no value for `groupBy.field`. |
243
+ | `selection.enabled` | Makes the checkbox column interactive; without it the column only displays the value. |
244
+ | `selection.disabledFn` | Disables the checkbox of some rows. |
245
+
246
+ Outputs: `selectionChange` emits `{ field, row, value, previousValue }` for one checkbox, and `groupSelectionChange`
247
+ emits `{ field, groupKey, groupValue, rows, value, previousState }` for a group checkbox. The checkbox writes the
248
+ boolean into the row property itself, so the rows of `config.data` always hold the current selection. Both
249
+ `lib-easy-table` and `lib-easy-table-basic` support `groupBy` and checkbox columns; the child table of
250
+ `lib-easy-table` reports its own checkboxes through `childSelectionChange`.
251
+
252
+ ## Toolbar
253
+
254
+ `ToolbarConfig` and `ToolbarTranslations` control the toolbar of a table. The buttons depend on the `can*` flags of
255
+ the table configuration (`canCreate`, `canExport`, `canImport`, ...). `ToolbarConfig.saveState`
256
+ (`'pending' | 'saving' | 'saved' | 'error'`) drives the label and state of the save button, and
257
+ `ToolbarTranslations` holds the label keys (`addBtn`, `saveBtn`, `importBtn`, `exportBtn`, ...), which are
258
+ translated with ngx-translate. A custom button is added with `customActionEnable`, `customActionIcon` and
259
+ `customActionTitle`. The table emits `addItem`, `save`, `importData` and `customAction`.
260
+
261
+ ```typescript
262
+ const config = new EasyTableConfig({
263
+ data: rows,
264
+ displayedColumns: columns,
265
+ canCreate: true,
266
+ canImport: true,
267
+ toolbarConfig: new ToolbarConfig({
268
+ icon: 'groups',
269
+ saveState: 'pending',
270
+ translations: { title: 'MY_TABLE', importBtn: 'MY_IMPORT' }
271
+ })
272
+ });
273
+ ```
274
+
275
+ ## File upload
276
+
277
+ `lib-easy-file-upload` picks files with a button, a drop area, or both, validates them, and can parse a CSV file into
278
+ a table configuration. It implements `ControlValueAccessor` and `Validator`, so it also works with `formControl` and
279
+ `ngModel`.
280
+
281
+ ```typescript
282
+ import { EasyFileUpload, EasyFileUploadResult, EasyFileUploadTableOutput } from 'easy-mat-ui';
283
+ ```
284
+
285
+ ```html
286
+ <lib-easy-file-upload
287
+ mode="both"
288
+ accept=".csv"
289
+ outputMode="easy-basic-table"
290
+ [maxFileSize]="1048576"
291
+ [tableConfig]="{ changePageSize: 5, readonly: true }"
292
+ (resultChange)="onResult($event)"
293
+ (fileRejected)="onRejected($event)" />
294
+ ```
295
+
296
+ | Input | Values and effect |
297
+ |---|---|
298
+ | `mode` | `'button'`, `'drag-drop'` or `'both'`. |
299
+ | `accept`, `multiple`, `maxFiles`, `maxFileSize` | Constraints on the files. Rejected files are reported by `fileRejected` and shown under the control. |
300
+ | `duplicates` | `'reject'` (default), `'replace'` or `'allow'`. |
301
+ | `outputMode` | `'raw'` (the files only, default), `'easy-table'` or `'easy-basic-table'` (a CSV file is parsed into an `EasyTableConfig`). |
302
+ | `delimiter`, `withHeader`, `encoding` | CSV parsing, `'auto'` by default. |
303
+ | `layout`, `appearance`, `buttonAppearance`, `buttonSize`, `compact` | Look of the control. |
304
+ | `label`, `hint`, `browseLabel`, `dropTitle`, `dropDescription`, `messages` | Texts. |
305
+ | `autoProcess`, `parse`, `loading`, `disabled`, `required` | Behavior and state. |
306
+
307
+ Outputs: `filesChange`, `resultChange` (an `EasyFileUploadResult` with `files`, `parsedFiles`, `output` and
308
+ `errors`), `fileRejected` and `fileRemoved`. The CSV parser is exported too: `parseCsv`, `detectCsvDelimiter` and `detectCsvHeader`.
309
+
191
310
  ## Generate a page
192
311
 
193
312
  Every admin screen starts the same way: a header, a few figures, a table, a model, a table configuration, translations.
@@ -268,15 +387,17 @@ It shows what the library is for: **almost nothing to code**. Every page is four
268
387
  | `<page>.ts` | Loads data from the service and saves the dialog results |
269
388
  | `<page>.scss` | Page styles |
270
389
 
271
- Three pages, built on every country of the world (Algeria first) and their cities:
390
+ Five pages, built on every country of the world (Algeria first) and their cities:
272
391
 
273
392
  1. **Countries and their cities**: expandable rows; the child table is loaded when a row opens.
274
393
  2. **Child tables in tabs**: `childConfig` as an array, one tab per configuration.
275
394
  3. **Cities of any country**: one full table with header filters, flags, status icons and a complete
276
395
  add / edit / view / delete dialog.
396
+ 4. **Selection**: countries grouped by continent, *Expand all* / *Collapse all*, checkbox columns, group checkboxes and the selection events.
397
+ 5. **Upload**: `lib-easy-file-upload` as a drop area with a button, as a button, and as a drop area, with a CSV file parsed into a table.
277
398
 
278
399
  Each page has a *Show the code of this page* panel with its real source files, and the header has a
279
- Light / Dark / System theme switcher.
400
+ Light / Dark theme switcher.
280
401
 
281
402
  Key points of the configuration:
282
403