easy-mat-ui 0.0.7 → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Redouane Chaibi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,63 +1,482 @@
1
- # EasyMatUi
2
-
3
- This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 19.2.0.
4
-
5
- ## Code scaffolding
6
-
7
- Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
8
-
9
- ```bash
10
- ng generate component component-name
11
- ```
12
-
13
- For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
14
-
15
- ```bash
16
- ng generate --help
17
- ```
18
-
19
- ## Building
20
-
21
- To build the library, run:
22
-
23
- ```bash
24
- ng build easy-mat-ui
25
- ```
26
-
27
- This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
28
-
29
- ### Publishing the Library
30
-
31
- Once the project is built, you can publish your library by following these steps:
32
-
33
- 1. Navigate to the `dist` directory:
34
- ```bash
35
- cd dist/easy-mat-ui
36
- ```
37
-
38
- 2. Run the `npm publish` command to publish your library to the npm registry:
39
- ```bash
40
- npm publish
41
- ```
42
-
43
- ## Running unit tests
44
-
45
- To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
46
-
47
- ```bash
48
- ng test
49
- ```
50
-
51
- ## Running end-to-end tests
52
-
53
- For end-to-end (e2e) testing, run:
54
-
55
- ```bash
56
- ng e2e
57
- ```
58
-
59
- Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
60
-
61
- ## Additional Resources
62
-
63
- For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/logo.svg" alt="Easy Mat UI" width="300">
4
+
5
+ **Data tables and reusable UI components for Angular Material.**
6
+
7
+ Describe a table in one configuration object: column filters, pagination, a create / edit / view dialog, child tables and light and dark themes.
8
+
9
+ [![npm](https://img.shields.io/npm/v/easy-mat-ui.svg)](https://www.npmjs.com/package/easy-mat-ui)
10
+ [![CI](https://github.com/chaibiredouane/easy-mat-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/chaibiredouane/easy-mat-ui/actions/workflows/ci.yml)
11
+ [![Angular](https://img.shields.io/badge/Angular-20%20%7C%2021%20%7C%2022-dd0031.svg)](https://angular.dev)
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/chaibiredouane/easy-mat-ui/blob/main/LICENSE)
13
+
14
+ **[Live demo](https://easy-mat-ui.web.app/)** · **[Try it on StackBlitz](https://stackblitz.com/github/chaibiredouane/easy-mat-ui/tree/main/examples/stackblitz-starter)** · **[Documentation](https://easy-mat-ui.web.app/docs/)** · [npm](https://www.npmjs.com/package/easy-mat-ui) · [Changelog](https://github.com/chaibiredouane/easy-mat-ui/blob/main/CHANGELOG.md)
15
+
16
+ <img src="https://raw.githubusercontent.com/chaibiredouane/easy-mat-ui/main/docs/images/demo.gif" alt="Easy Mat UI demo: filtering a table from its column headers, editing a row in a dialog, switching to dark mode, and the page builder" width="860">
17
+
18
+ </div>
19
+
20
+ > Angular Material gives you the building blocks. Easy Mat UI is a layer on top of it for the screens you rebuild in every project: a data table with its filters, pagination and edit dialog, described once.
21
+
22
+ A set of customizable Angular Material components built around a configurable **data table**:
23
+ filtering, sorting, pagination, typed columns, expandable rows, tabbed child tables, a toolbar,
24
+ a configurable **create / edit / view dialog** and a **multi-select** control, with
25
+ [ngx-translate](https://github.com/ngx-translate/core) based i18n.
26
+
27
+ ## Features
28
+
29
+ - `lib-easy-table` / `lib-easy-table-basic`: a Material table driven by a single `EasyTableConfig` object.
30
+ - Typed columns (`MatColumnTyped`): text, number, date, date-time, icon, icon-and-text, button, dropdown list, image
31
+ (flags), password and filter columns.
32
+ - **Column filters** under the titles (a compact text input or a multi-select per column), global search, sorting,
33
+ pagination, sticky columns and a header that stays pinned while the rows scroll.
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.
39
+ - `EasyDialogService`: a configurable dialog to create, edit or view a record.
40
+ - `lib-easy-multi-select`: a searchable multi-select with select-all, clear, read-only and compact modes, or a single-choice dropdown (`single`).
41
+ - Reusable interface components, each with `@Input()` / `@Output()` and a typed model: `lib-easy-segmented`,
42
+ `lib-easy-chip-nav`, `lib-easy-language-switch`, `lib-easy-card` / `lib-easy-card-grid`, `lib-easy-stat` and
43
+ `lib-easy-page-header`.
44
+ - **Page generation**: the *Page builder* of the demo and the `npx easy-mat-ui add-page` command generate a page from these components and a table (see [Generate a page](#generate-a-page)).
45
+ - **Light and dark themes** switchable at runtime (`EasyThemeService`), driven by CSS variables.
46
+ - Responsive layout (tables adapt below 768 px and 1024 px) and no WCAG 2 A/AA violation reported by axe-core on the demo.
47
+ - Shared models, enums and configuration classes exported from one entry point.
48
+
49
+ ## Screenshots
50
+
51
+ Taken from the [live demo](https://easy-mat-ui.web.app/) (version 1.1.0), not mocked up.
52
+
53
+ | Light | Dark |
54
+ |---|---|
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"> |
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"> |
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
+
62
+ ## Requirements and supported versions
63
+
64
+ `easy-mat-ui` supports **Angular 20, 21 and 22** with the same code. The
65
+ peer dependencies accept all three majors. Every pull request builds the library, runs its unit tests, and compiles
66
+ the pages the generator writes and the documentation examples against each of them (see [CI](https://github.com/chaibiredouane/easy-mat-ui/blob/main/.github/workflows/ci.yml)).
67
+
68
+ | easy-mat-ui | Angular | Checked by CI | Status |
69
+ |---|---|---|---|
70
+ | **1.x** | 20, 21, 22 | build, unit tests, generator, examples, on each major | Active |
71
+ | `easy-mat-ui-ng20` 20.x | 20 | n/a | Deprecated, replaced by `easy-mat-ui` 1.x |
72
+
73
+ The demo was also compared by screenshot (light and dark themes, five pages) on Angular 20, 21 and 22 on 5 November 2026: the
74
+ pages are identical, except that the Arabic names of the cities table are aligned to the right of their cell on 21 and
75
+ 22 and to the left on 20. If you see another visual difference, please [open an issue](https://github.com/chaibiredouane/easy-mat-ui/issues/new?template=bug_report.yml).
76
+
77
+ Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms`, `@angular/cdk`,
78
+ `@angular/material`, `@angular/platform-browser` (all `^20.0.0 || ^21.0.0 || ^22.0.0`), `@ngx-translate/core` `^16`,
79
+ `bootstrap` `^5`, `rxjs` `^7`. Optional: `@ngx-translate/http-loader`, `flag-icons` (country columns).
80
+
81
+ ## Status and limits
82
+
83
+ - **A young project.** The first release (as `easy-mat-ui-ng20` 20.0.0) is from 3 November 2026, and the library is maintained by one person. Feedback and [contributions](https://github.com/chaibiredouane/easy-mat-ui/blob/main/CONTRIBUTING.md) are welcome; security reports go through [SECURITY.md](https://github.com/chaibiredouane/easy-mat-ui/blob/main/SECURITY.md).
84
+ - **Angular 20, 21 and 22.** One package, `easy-mat-ui`, for all three (see [Requirements](#requirements-and-supported-versions)). It replaces `easy-mat-ui-ng20`, see [Migrating](#migrating-from-easy-mat-ui-ng20).
85
+ - **Data is handled in the browser.** There is no server-side paging and no virtual scrolling. For hundreds of thousands of rows, or spreadsheet-style editing, use a grid built for that, such as AG Grid or TanStack Table.
86
+ - **Click-to-sort is off when header filters are on** (`withFilterInHeader: true`). Use the global search, or leave the header filters off, if you need sorting.
87
+ - **Checked on every pull request:** the build, the unit tests, a compile check of the pages the generator writes and of the code examples of the documentation.
88
+
89
+ ## Installation
90
+
91
+ Want to see it first? The [starter project on StackBlitz](https://stackblitz.com/github/chaibiredouane/easy-mat-ui/tree/main/examples/stackblitz-starter) runs in your browser, with nothing to install. Its source is in [`examples/stackblitz-starter`](https://github.com/chaibiredouane/easy-mat-ui/tree/main/examples/stackblitz-starter).
92
+
93
+ ```bash
94
+ npm install easy-mat-ui
95
+ ```
96
+
97
+ Install the peer dependencies if your project does not have them yet:
98
+
99
+ ```bash
100
+ ng add @angular/material
101
+ npm install @ngx-translate/core@^16 @ngx-translate/http-loader@^16 bootstrap
102
+ ```
103
+
104
+ Keep ngx-translate on version 16: a plain `npm install @ngx-translate/core` installs a newer major version, which this
105
+ library does not support yet (for example `provideTranslateService({ defaultLanguage: 'en' })` no longer compiles).
106
+
107
+ The components use Material icons. `ng add @angular/material` normally takes care of it; otherwise add the
108
+ font to your `index.html`:
109
+
110
+ ```html
111
+ <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
112
+ ```
113
+
114
+ ### Bundle size budget
115
+
116
+ A new Angular project fails `ng build` in production with *"bundle initial exceeded maximum budget"* once Angular Material
117
+ and this library are added: two components embed the Bootstrap stylesheet (a slimmer stylesheet is planned for 20.1). Raise the
118
+ initial budget in `angular.json` (measured: about 1.9 MB raw, 254 kB transferred, for the quick start below):
119
+
120
+ ```json
121
+ "budgets": [
122
+ { "type": "initial", "maximumWarning": "2.5MB", "maximumError": "4MB" }
123
+ ]
124
+ ```
125
+
126
+ ## Migrating from `easy-mat-ui-ng20`
127
+
128
+ The package was renamed; the API is unchanged.
129
+
130
+ 1. `npm uninstall easy-mat-ui-ng20 && npm install easy-mat-ui`
131
+ 2. Replace `easy-mat-ui-ng20` with `easy-mat-ui` in your imports (and in `angular.json` if a style path mentions it).
132
+ 3. `ng build`
133
+
134
+ ## Quick start
135
+
136
+ Provide ngx-translate once in your application config:
137
+
138
+ ```typescript
139
+ import { ApplicationConfig } from '@angular/core';
140
+ import { provideTranslateService } from '@ngx-translate/core';
141
+
142
+ export const appConfig: ApplicationConfig = {
143
+ providers: [provideTranslateService({ defaultLanguage: 'en' })]
144
+ };
145
+ ```
146
+
147
+ Use the table in a standalone component:
148
+
149
+ ```typescript
150
+ import { Component } from '@angular/core';
151
+ import { EasyTableComponent, EasyTableConfig, MatColumnTyped } from 'easy-mat-ui';
152
+
153
+ @Component({
154
+ selector: 'app-users',
155
+ standalone: true,
156
+ imports: [EasyTableComponent],
157
+ template: `<lib-easy-table [config]="config"></lib-easy-table>`
158
+ })
159
+ export class UsersComponent {
160
+ config: Partial<EasyTableConfig> = {
161
+ data: [
162
+ { id: 1, name: 'Alice' },
163
+ { id: 2, name: 'Bob' }
164
+ ],
165
+ displayedColumns: [
166
+ new MatColumnTyped({ name: 'id' }),
167
+ new MatColumnTyped({ name: 'name' })
168
+ ],
169
+ canCreate: true,
170
+ canUpdate: true,
171
+ canDelete: true
172
+ };
173
+ }
174
+ ```
175
+
176
+ Table events are exposed as outputs: `addItem`, `editItem`, `viewItem`, `deleteItem`, `customAction`,
177
+ `clickField`, and more (see `EasyTableComponent`).
178
+
179
+ ## Dialog example
180
+
181
+ ```typescript
182
+ import { inject } from '@angular/core';
183
+ import { CRUD, EasyDialogService, MatColumnTyped } from 'easy-mat-ui';
184
+
185
+ const dialog = inject(EasyDialogService);
186
+
187
+ dialog.open({
188
+ title: 'Edit user',
189
+ pk: 'id',
190
+ action: CRUD.UPDATE,
191
+ data: { id: 1, name: 'Alice' },
192
+ fields: [
193
+ new MatColumnTyped({ name: 'id', order: 1 }),
194
+ new MatColumnTyped({ name: 'name', order: 2, isRequired: true })
195
+ ]
196
+ }).afterClosed().subscribe(result => console.log(result?.event, result?.data));
197
+ ```
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
+
310
+ ## Generate a page
311
+
312
+ Every admin screen starts the same way: a header, a few figures, a table, a model, a table configuration, translations.
313
+ Easy Mat UI lets you generate that starting point instead of typing it, in two ways that share **one generator**:
314
+
315
+ | | Page builder | `add-page` command |
316
+ |---|---|---|
317
+ | Where | A page of the [live demo](https://easy-mat-ui.web.app/), in your browser | Your terminal, in an Angular project |
318
+ | You | Click the components you want, define the fields, see a live preview | Answer a few questions, or pass options |
319
+ | You get | The generated files to copy, the command to run, and a downloadable description (`.page.json`) | The files written in your project, at the right place |
320
+ | Installs anything | No | No |
321
+
322
+ ### The idea
323
+
324
+ 1. **Describe** the page: which components (page header, key figures, category buttons, segmented control, language
325
+ picker, card grid, a data table with an optional child table) and, for the table, the fields of its model.
326
+ 2. **Generate** the code from that description: a standalone component, its template, the table configuration and the
327
+ models. Nothing is hidden: it is ordinary Angular code that uses the components of this library.
328
+ 3. **Own it**: the result is a starting point. You edit it and connect your own data (a service, an API call). The
329
+ generator does not touch your code afterwards.
330
+
331
+ ### Page builder (in the browser)
332
+
333
+ Open the *Page builder* of the [live demo](https://easy-mat-ui.web.app/). Choose the components, add the fields of the
334
+ table (text, number, date, yes/no), and switch filters or the child table on. The preview uses the real components, so
335
+ what you see is what the code does. Then:
336
+
337
+ - copy the generated files one by one;
338
+ - copy the exact command that reproduces the page in your project;
339
+ - download the description of the page (`my-page.page.json`) to hand it to the command below.
340
+
341
+ It is also a quick way to discover which components exist and how they fit together, without installing anything.
342
+
343
+ ### `add-page` command (in your project)
344
+
345
+ ```bash
346
+ npx easy-mat-ui add-page # asks what it needs
347
+ npx easy-mat-ui add-page --name stock-items --blocks page-header,stat,table --dry-run --print
348
+ npx easy-mat-ui add-page --config my-page.page.json # the description downloaded from the Page builder
349
+ ```
350
+
351
+ Run it at the root of your Angular project. `--dry-run --print` shows what would be written and writes nothing, which is
352
+ the safe way to try it. `--help` lists every option.
353
+
354
+ - **Models**: an existing `*.model.ts` that matches the page name is reused. Otherwise a generic model (`item1`,
355
+ `item2`, `item3`) is generated, with example rows and text, icon and action columns. Field types it cannot map (for
356
+ example `string[]`) are ignored instead of producing code that does not compile.
357
+ - **Translations**: with ngx-translate the code uses translation keys, and the new entries are added to your English
358
+ file. Without it the texts are written in the code. Nothing is ever installed.
359
+ - **Quality**: the generator has unit tests, and the continuous integration compiles the generated pages with strict
360
+ Angular templates, so generated code that stops compiling fails the build.
361
+
362
+ ### What it does not do
363
+
364
+ - It generates a **starting point, not a finished screen**: the logic and the data calls are yours.
365
+ - It does not call an API and does not create routes for you.
366
+ - It generates code for the components of `easy-mat-ui`, not generic Angular Material code.
367
+
368
+ ## Demo application
369
+
370
+ The repository contains a runnable demo in [`projects/demo`](projects/demo). It needs no backend: a mock service
371
+ (`GeoService`) returns Observables like a real `HttpClient` service would, so replacing it is the only change a real
372
+ application needs.
373
+
374
+ ```bash
375
+ git clone https://github.com/chaibiredouane/easy-mat-ui.git
376
+ cd easy-mat-ui
377
+ npm ci
378
+ npm start # http://localhost:4200
379
+ ```
380
+
381
+ It shows what the library is for: **almost nothing to code**. Every page is four small files, in the same layout:
382
+
383
+ | File | Role |
384
+ |---|---|
385
+ | `<page>.config.ts` | The whole configuration: columns, dialog fields, table options, tabs |
386
+ | `<page>.html` | A few lines: `<lib-easy-table [config]="..." [childConfig]="...">` and its events |
387
+ | `<page>.ts` | Loads data from the service and saves the dialog results |
388
+ | `<page>.scss` | Page styles |
389
+
390
+ Five pages, built on every country of the world (Algeria first) and their cities:
391
+
392
+ 1. **Countries and their cities**: expandable rows; the child table is loaded when a row opens.
393
+ 2. **Child tables in tabs**: `childConfig` as an array, one tab per configuration.
394
+ 3. **Cities of any country**: one full table with header filters, flags, status icons and a complete
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.
398
+
399
+ Each page has a *Show the code of this page* panel with its real source files, and the header has a
400
+ Light / Dark theme switcher.
401
+
402
+ Key points of the configuration:
403
+
404
+ - `childConfig` takes one configuration, or an array to get tabs (`tabTitle`, `tabIcon`).
405
+ - `isExpanded: true` on the parent adds the expand button; `extendRow` tells you which row opened.
406
+ - `sortedBy: ''` keeps the order given by your service (by default the rows are ordered by their `id` property: numbers as numbers, anything else as text).
407
+ - Rebuild a table configuration (a new `EasyTableConfig`) whenever its data changes.
408
+
409
+ The demo data lives under `projects/demo/src/app/data` and is **not** part of the npm package. Countries and cities
410
+ come from [GeoNames](https://www.geonames.org/) (CC BY 4.0), the administrative divisions of Algeria from Wikipedia
411
+ (CC BY-SA 4.0): see `DATA-LICENSE.md` and `WORLD-DATA-SOURCES.md` in that folder. Populations are source values of varying
412
+ years, not a census.
413
+
414
+ ## Themes
415
+
416
+ Light and dark themes are driven by CSS variables (`--text-color`, `--card-bg`, `--border-color`,
417
+ `--color-primary-blue`, `--radius-md`, `--shadow-md`, ...), so an application can override them without touching the
418
+ library. `EasyThemeService` switches theme at runtime, without reloading the page:
419
+
420
+ ```typescript
421
+ import { inject } from '@angular/core';
422
+ import { EasyThemeService } from 'easy-mat-ui';
423
+
424
+ const theme = inject(EasyThemeService);
425
+ theme.setTheme('dark'); // 'light' | 'dark' | 'system' (follows the operating system, live)
426
+ theme.toggle();
427
+ theme.theme(); // the applied theme, as a signal
428
+ ```
429
+
430
+ The service does nothing until you call it, never stores anything unless you give it a `storageKey`
431
+ (`EASY_THEME_OPTIONS`), and only adds the `dark-theme` class to `<body>` (the class the library stylesheet already
432
+ used) and a `data-easy-theme` attribute on `<html>`. Applications that toggle `dark-theme` themselves keep working.
433
+ Material components follow when your Angular Material theme uses `color-scheme` (for example `mat.theme`).
434
+
435
+ ## Responsive and accessibility
436
+
437
+ Below 768 px, tables size their columns to their content and scroll horizontally, and the sticky actions column shrinks
438
+ to its buttons so the data stays visible. The demo is checked at 320, 375, 430, 768, 1024, 1440 and 1920 px in both
439
+ themes (no horizontal overflow, no console error) and with axe-core (no WCAG 2 A/AA violation on the demo pages).
440
+
441
+ ## Styles
442
+
443
+ Components embed their own styles. To also get the shared classes (`green`, `red`, `taupe`, `bg-*`,
444
+ spacing and Material overrides), add the stylesheet to the `styles` array of your `angular.json`:
445
+
446
+ ```json
447
+ "styles": [
448
+ "node_modules/easy-mat-ui/styles/styles.scss",
449
+ "node_modules/flag-icons/css/flag-icons.min.css"
450
+ ]
451
+ ```
452
+
453
+ `flag-icons` is only needed for flag columns (`ColumnType.IMAGE` with a country code such as `fr`); its stylesheet is not bundled with the components.
454
+
455
+ > **Troubleshooting:** with the Angular `application` builder, the `flag-icons` stylesheet can fail in
456
+ > development with `Two output files share the same path but have different contents: media/xx.svg`.
457
+ > Set `"outputHashing": "media"` in the `development` configuration of the `build` target of your
458
+ > `angular.json`.
459
+
460
+ ## Versioning
461
+
462
+ The library version follows [Semantic Versioning](https://semver.org/): PATCH for bug fixes, MINOR for
463
+ backward-compatible features, MAJOR for breaking changes. The first number is the major version of this library, not of Angular: the supported Angular range is in the peer
464
+ dependencies. Support for a new Angular major is added in a minor release; dropping the oldest one is a major release. See [CHANGELOG.md](https://github.com/chaibiredouane/easy-mat-ui/blob/main/CHANGELOG.md).
465
+
466
+ ## Development
467
+
468
+ ```bash
469
+ npm ci
470
+ npm start # runs the demo application
471
+ npm run build # builds the library into dist/easy-mat-ui
472
+ npm test # runs the unit tests (headless Chrome)
473
+ ```
474
+
475
+ ## Contributing
476
+
477
+ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the
478
+ [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
479
+
480
+ ## License
481
+
482
+ [MIT](LICENSE)