easy-mat-ui 0.0.7 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +361 -63
- package/fesm2022/easy-mat-ui.mjs +2183 -428
- package/fesm2022/easy-mat-ui.mjs.map +1 -1
- package/index.d.ts +911 -54
- package/package.json +59 -22
- package/page-generator/blocks.js +155 -0
- package/page-generator/catalog.js +132 -0
- package/page-generator/cli/main.js +314 -0
- package/page-generator/cli/project.js +252 -0
- package/page-generator/context.js +108 -0
- package/page-generator/generate.js +182 -0
- package/page-generator/index.js +33 -0
- package/page-generator/naming.js +53 -0
- package/page-generator/table.js +310 -0
- package/page-generator/types.js +6 -0
- package/styles/styles/_backgrounds.scss +39 -0
- package/styles/styles/_buttons.scss +90 -0
- package/styles/styles/_colors.scss +197 -0
- package/styles/styles/_effects.scss +44 -0
- package/styles/styles/_material-overrides.scss +106 -0
- package/styles/styles/_spacing.scss +68 -0
- package/styles/styles/_tables.scss +569 -0
- package/styles/styles/_typography.scss +100 -0
- package/styles/styles.scss +29 -0
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,361 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/easy-mat-ui)
|
|
10
|
+
[](https://github.com/chaibiredouane/easy-mat-ui/actions/workflows/ci.yml)
|
|
11
|
+
[](https://angular.dev)
|
|
12
|
+
[](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
|
+
- `EasyDialogService`: a configurable dialog to create, edit or view a record.
|
|
36
|
+
- `lib-easy-multi-select`: a searchable multi-select with select-all, clear, read-only and compact modes, or a single-choice dropdown (`single`).
|
|
37
|
+
- Reusable interface components, each with `@Input()` / `@Output()` and a typed model: `lib-easy-segmented`,
|
|
38
|
+
`lib-easy-chip-nav`, `lib-easy-language-switch`, `lib-easy-card` / `lib-easy-card-grid`, `lib-easy-stat` and
|
|
39
|
+
`lib-easy-page-header`.
|
|
40
|
+
- **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)).
|
|
41
|
+
- **Light and dark themes** switchable at runtime (`EasyThemeService`), driven by CSS variables.
|
|
42
|
+
- Responsive layout (tables adapt below 768 px and 1024 px) and no WCAG 2 A/AA violation reported by axe-core on the demo.
|
|
43
|
+
- Shared models, enums and configuration classes exported from one entry point.
|
|
44
|
+
|
|
45
|
+
## Screenshots
|
|
46
|
+
|
|
47
|
+
Taken from the [live demo](https://easy-mat-ui.web.app/) (version 20.0.6), not mocked up.
|
|
48
|
+
|
|
49
|
+
| Light | Dark |
|
|
50
|
+
|---|---|
|
|
51
|
+
| <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
|
+
| <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
|
+
|
|
54
|
+
## Requirements and supported versions
|
|
55
|
+
|
|
56
|
+
`easy-mat-ui` supports **Angular 20, 21 and 22** with the same code. The
|
|
57
|
+
peer dependencies accept all three majors. Every pull request builds the library, runs its unit tests, and compiles
|
|
58
|
+
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)).
|
|
59
|
+
|
|
60
|
+
| easy-mat-ui | Angular | Checked by CI | Status |
|
|
61
|
+
|---|---|---|---|
|
|
62
|
+
| **1.x** | 20, 21, 22 | build, unit tests, generator, examples, on each major | Active |
|
|
63
|
+
| `easy-mat-ui-ng20` 20.x | 20 | n/a | Deprecated, replaced by `easy-mat-ui` 1.x |
|
|
64
|
+
|
|
65
|
+
The demo was also compared by screenshot (light and dark themes, five pages) on Angular 20, 21 and 22 on 5 November 2026: the
|
|
66
|
+
pages are identical, except that the Arabic names of the cities table are aligned to the right of their cell on 21 and
|
|
67
|
+
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).
|
|
68
|
+
|
|
69
|
+
Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms`, `@angular/cdk`,
|
|
70
|
+
`@angular/material`, `@angular/platform-browser` (all `^20.0.0 || ^21.0.0 || ^22.0.0`), `@ngx-translate/core` `^16`,
|
|
71
|
+
`bootstrap` `^5`, `rxjs` `^7`. Optional: `@ngx-translate/http-loader`, `flag-icons` (country columns).
|
|
72
|
+
|
|
73
|
+
## Status and limits
|
|
74
|
+
|
|
75
|
+
- **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).
|
|
76
|
+
- **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).
|
|
77
|
+
- **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.
|
|
78
|
+
- **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.
|
|
79
|
+
- **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.
|
|
80
|
+
|
|
81
|
+
## Installation
|
|
82
|
+
|
|
83
|
+
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).
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
npm install easy-mat-ui
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Install the peer dependencies if your project does not have them yet:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
ng add @angular/material
|
|
93
|
+
npm install @ngx-translate/core@^16 @ngx-translate/http-loader@^16 bootstrap
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Keep ngx-translate on version 16: a plain `npm install @ngx-translate/core` installs a newer major version, which this
|
|
97
|
+
library does not support yet (for example `provideTranslateService({ defaultLanguage: 'en' })` no longer compiles).
|
|
98
|
+
|
|
99
|
+
The components use Material icons. `ng add @angular/material` normally takes care of it; otherwise add the
|
|
100
|
+
font to your `index.html`:
|
|
101
|
+
|
|
102
|
+
```html
|
|
103
|
+
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Bundle size budget
|
|
107
|
+
|
|
108
|
+
A new Angular project fails `ng build` in production with *"bundle initial exceeded maximum budget"* once Angular Material
|
|
109
|
+
and this library are added: two components embed the Bootstrap stylesheet (a slimmer stylesheet is planned for 20.1). Raise the
|
|
110
|
+
initial budget in `angular.json` (measured: about 1.9 MB raw, 254 kB transferred, for the quick start below):
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
"budgets": [
|
|
114
|
+
{ "type": "initial", "maximumWarning": "2.5MB", "maximumError": "4MB" }
|
|
115
|
+
]
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Migrating from `easy-mat-ui-ng20`
|
|
119
|
+
|
|
120
|
+
The package was renamed; the API is unchanged.
|
|
121
|
+
|
|
122
|
+
1. `npm uninstall easy-mat-ui-ng20 && npm install easy-mat-ui`
|
|
123
|
+
2. Replace `easy-mat-ui-ng20` with `easy-mat-ui` in your imports (and in `angular.json` if a style path mentions it).
|
|
124
|
+
3. `ng build`
|
|
125
|
+
|
|
126
|
+
## Quick start
|
|
127
|
+
|
|
128
|
+
Provide ngx-translate once in your application config:
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
import { ApplicationConfig } from '@angular/core';
|
|
132
|
+
import { provideTranslateService } from '@ngx-translate/core';
|
|
133
|
+
|
|
134
|
+
export const appConfig: ApplicationConfig = {
|
|
135
|
+
providers: [provideTranslateService({ defaultLanguage: 'en' })]
|
|
136
|
+
};
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Use the table in a standalone component:
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
import { Component } from '@angular/core';
|
|
143
|
+
import { EasyTableComponent, EasyTableConfig, MatColumnTyped } from 'easy-mat-ui';
|
|
144
|
+
|
|
145
|
+
@Component({
|
|
146
|
+
selector: 'app-users',
|
|
147
|
+
standalone: true,
|
|
148
|
+
imports: [EasyTableComponent],
|
|
149
|
+
template: `<lib-easy-table [config]="config"></lib-easy-table>`
|
|
150
|
+
})
|
|
151
|
+
export class UsersComponent {
|
|
152
|
+
config: Partial<EasyTableConfig> = {
|
|
153
|
+
data: [
|
|
154
|
+
{ id: 1, name: 'Alice' },
|
|
155
|
+
{ id: 2, name: 'Bob' }
|
|
156
|
+
],
|
|
157
|
+
displayedColumns: [
|
|
158
|
+
new MatColumnTyped({ name: 'id' }),
|
|
159
|
+
new MatColumnTyped({ name: 'name' })
|
|
160
|
+
],
|
|
161
|
+
canCreate: true,
|
|
162
|
+
canUpdate: true,
|
|
163
|
+
canDelete: true
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Table events are exposed as outputs: `addItem`, `editItem`, `viewItem`, `deleteItem`, `customAction`,
|
|
169
|
+
`clickField`, and more (see `EasyTableComponent`).
|
|
170
|
+
|
|
171
|
+
## Dialog example
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
import { inject } from '@angular/core';
|
|
175
|
+
import { CRUD, EasyDialogService, MatColumnTyped } from 'easy-mat-ui';
|
|
176
|
+
|
|
177
|
+
const dialog = inject(EasyDialogService);
|
|
178
|
+
|
|
179
|
+
dialog.open({
|
|
180
|
+
title: 'Edit user',
|
|
181
|
+
pk: 'id',
|
|
182
|
+
action: CRUD.UPDATE,
|
|
183
|
+
data: { id: 1, name: 'Alice' },
|
|
184
|
+
fields: [
|
|
185
|
+
new MatColumnTyped({ name: 'id', order: 1 }),
|
|
186
|
+
new MatColumnTyped({ name: 'name', order: 2, isRequired: true })
|
|
187
|
+
]
|
|
188
|
+
}).afterClosed().subscribe(result => console.log(result?.event, result?.data));
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Generate a page
|
|
192
|
+
|
|
193
|
+
Every admin screen starts the same way: a header, a few figures, a table, a model, a table configuration, translations.
|
|
194
|
+
Easy Mat UI lets you generate that starting point instead of typing it, in two ways that share **one generator**:
|
|
195
|
+
|
|
196
|
+
| | Page builder | `add-page` command |
|
|
197
|
+
|---|---|---|
|
|
198
|
+
| Where | A page of the [live demo](https://easy-mat-ui.web.app/), in your browser | Your terminal, in an Angular project |
|
|
199
|
+
| You | Click the components you want, define the fields, see a live preview | Answer a few questions, or pass options |
|
|
200
|
+
| 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 |
|
|
201
|
+
| Installs anything | No | No |
|
|
202
|
+
|
|
203
|
+
### The idea
|
|
204
|
+
|
|
205
|
+
1. **Describe** the page: which components (page header, key figures, category buttons, segmented control, language
|
|
206
|
+
picker, card grid, a data table with an optional child table) and, for the table, the fields of its model.
|
|
207
|
+
2. **Generate** the code from that description: a standalone component, its template, the table configuration and the
|
|
208
|
+
models. Nothing is hidden: it is ordinary Angular code that uses the components of this library.
|
|
209
|
+
3. **Own it**: the result is a starting point. You edit it and connect your own data (a service, an API call). The
|
|
210
|
+
generator does not touch your code afterwards.
|
|
211
|
+
|
|
212
|
+
### Page builder (in the browser)
|
|
213
|
+
|
|
214
|
+
Open the *Page builder* of the [live demo](https://easy-mat-ui.web.app/). Choose the components, add the fields of the
|
|
215
|
+
table (text, number, date, yes/no), and switch filters or the child table on. The preview uses the real components, so
|
|
216
|
+
what you see is what the code does. Then:
|
|
217
|
+
|
|
218
|
+
- copy the generated files one by one;
|
|
219
|
+
- copy the exact command that reproduces the page in your project;
|
|
220
|
+
- download the description of the page (`my-page.page.json`) to hand it to the command below.
|
|
221
|
+
|
|
222
|
+
It is also a quick way to discover which components exist and how they fit together, without installing anything.
|
|
223
|
+
|
|
224
|
+
### `add-page` command (in your project)
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
npx easy-mat-ui add-page # asks what it needs
|
|
228
|
+
npx easy-mat-ui add-page --name stock-items --blocks page-header,stat,table --dry-run --print
|
|
229
|
+
npx easy-mat-ui add-page --config my-page.page.json # the description downloaded from the Page builder
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Run it at the root of your Angular project. `--dry-run --print` shows what would be written and writes nothing, which is
|
|
233
|
+
the safe way to try it. `--help` lists every option.
|
|
234
|
+
|
|
235
|
+
- **Models**: an existing `*.model.ts` that matches the page name is reused. Otherwise a generic model (`item1`,
|
|
236
|
+
`item2`, `item3`) is generated, with example rows and text, icon and action columns. Field types it cannot map (for
|
|
237
|
+
example `string[]`) are ignored instead of producing code that does not compile.
|
|
238
|
+
- **Translations**: with ngx-translate the code uses translation keys, and the new entries are added to your English
|
|
239
|
+
file. Without it the texts are written in the code. Nothing is ever installed.
|
|
240
|
+
- **Quality**: the generator has unit tests, and the continuous integration compiles the generated pages with strict
|
|
241
|
+
Angular templates, so generated code that stops compiling fails the build.
|
|
242
|
+
|
|
243
|
+
### What it does not do
|
|
244
|
+
|
|
245
|
+
- It generates a **starting point, not a finished screen**: the logic and the data calls are yours.
|
|
246
|
+
- It does not call an API and does not create routes for you.
|
|
247
|
+
- It generates code for the components of `easy-mat-ui`, not generic Angular Material code.
|
|
248
|
+
|
|
249
|
+
## Demo application
|
|
250
|
+
|
|
251
|
+
The repository contains a runnable demo in [`projects/demo`](projects/demo). It needs no backend: a mock service
|
|
252
|
+
(`GeoService`) returns Observables like a real `HttpClient` service would, so replacing it is the only change a real
|
|
253
|
+
application needs.
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
git clone https://github.com/chaibiredouane/easy-mat-ui.git
|
|
257
|
+
cd easy-mat-ui
|
|
258
|
+
npm ci
|
|
259
|
+
npm start # http://localhost:4200
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
It shows what the library is for: **almost nothing to code**. Every page is four small files, in the same layout:
|
|
263
|
+
|
|
264
|
+
| File | Role |
|
|
265
|
+
|---|---|
|
|
266
|
+
| `<page>.config.ts` | The whole configuration: columns, dialog fields, table options, tabs |
|
|
267
|
+
| `<page>.html` | A few lines: `<lib-easy-table [config]="..." [childConfig]="...">` and its events |
|
|
268
|
+
| `<page>.ts` | Loads data from the service and saves the dialog results |
|
|
269
|
+
| `<page>.scss` | Page styles |
|
|
270
|
+
|
|
271
|
+
Three pages, built on every country of the world (Algeria first) and their cities:
|
|
272
|
+
|
|
273
|
+
1. **Countries and their cities**: expandable rows; the child table is loaded when a row opens.
|
|
274
|
+
2. **Child tables in tabs**: `childConfig` as an array, one tab per configuration.
|
|
275
|
+
3. **Cities of any country**: one full table with header filters, flags, status icons and a complete
|
|
276
|
+
add / edit / view / delete dialog.
|
|
277
|
+
|
|
278
|
+
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.
|
|
280
|
+
|
|
281
|
+
Key points of the configuration:
|
|
282
|
+
|
|
283
|
+
- `childConfig` takes one configuration, or an array to get tabs (`tabTitle`, `tabIcon`).
|
|
284
|
+
- `isExpanded: true` on the parent adds the expand button; `extendRow` tells you which row opened.
|
|
285
|
+
- `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).
|
|
286
|
+
- Rebuild a table configuration (a new `EasyTableConfig`) whenever its data changes.
|
|
287
|
+
|
|
288
|
+
The demo data lives under `projects/demo/src/app/data` and is **not** part of the npm package. Countries and cities
|
|
289
|
+
come from [GeoNames](https://www.geonames.org/) (CC BY 4.0), the administrative divisions of Algeria from Wikipedia
|
|
290
|
+
(CC BY-SA 4.0): see `DATA-LICENSE.md` and `WORLD-DATA-SOURCES.md` in that folder. Populations are source values of varying
|
|
291
|
+
years, not a census.
|
|
292
|
+
|
|
293
|
+
## Themes
|
|
294
|
+
|
|
295
|
+
Light and dark themes are driven by CSS variables (`--text-color`, `--card-bg`, `--border-color`,
|
|
296
|
+
`--color-primary-blue`, `--radius-md`, `--shadow-md`, ...), so an application can override them without touching the
|
|
297
|
+
library. `EasyThemeService` switches theme at runtime, without reloading the page:
|
|
298
|
+
|
|
299
|
+
```typescript
|
|
300
|
+
import { inject } from '@angular/core';
|
|
301
|
+
import { EasyThemeService } from 'easy-mat-ui';
|
|
302
|
+
|
|
303
|
+
const theme = inject(EasyThemeService);
|
|
304
|
+
theme.setTheme('dark'); // 'light' | 'dark' | 'system' (follows the operating system, live)
|
|
305
|
+
theme.toggle();
|
|
306
|
+
theme.theme(); // the applied theme, as a signal
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
The service does nothing until you call it, never stores anything unless you give it a `storageKey`
|
|
310
|
+
(`EASY_THEME_OPTIONS`), and only adds the `dark-theme` class to `<body>` (the class the library stylesheet already
|
|
311
|
+
used) and a `data-easy-theme` attribute on `<html>`. Applications that toggle `dark-theme` themselves keep working.
|
|
312
|
+
Material components follow when your Angular Material theme uses `color-scheme` (for example `mat.theme`).
|
|
313
|
+
|
|
314
|
+
## Responsive and accessibility
|
|
315
|
+
|
|
316
|
+
Below 768 px, tables size their columns to their content and scroll horizontally, and the sticky actions column shrinks
|
|
317
|
+
to its buttons so the data stays visible. The demo is checked at 320, 375, 430, 768, 1024, 1440 and 1920 px in both
|
|
318
|
+
themes (no horizontal overflow, no console error) and with axe-core (no WCAG 2 A/AA violation on the demo pages).
|
|
319
|
+
|
|
320
|
+
## Styles
|
|
321
|
+
|
|
322
|
+
Components embed their own styles. To also get the shared classes (`green`, `red`, `taupe`, `bg-*`,
|
|
323
|
+
spacing and Material overrides), add the stylesheet to the `styles` array of your `angular.json`:
|
|
324
|
+
|
|
325
|
+
```json
|
|
326
|
+
"styles": [
|
|
327
|
+
"node_modules/easy-mat-ui/styles/styles.scss",
|
|
328
|
+
"node_modules/flag-icons/css/flag-icons.min.css"
|
|
329
|
+
]
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
`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.
|
|
333
|
+
|
|
334
|
+
> **Troubleshooting:** with the Angular `application` builder, the `flag-icons` stylesheet can fail in
|
|
335
|
+
> development with `Two output files share the same path but have different contents: media/xx.svg`.
|
|
336
|
+
> Set `"outputHashing": "media"` in the `development` configuration of the `build` target of your
|
|
337
|
+
> `angular.json`.
|
|
338
|
+
|
|
339
|
+
## Versioning
|
|
340
|
+
|
|
341
|
+
The library version follows [Semantic Versioning](https://semver.org/): PATCH for bug fixes, MINOR for
|
|
342
|
+
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
|
|
343
|
+
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).
|
|
344
|
+
|
|
345
|
+
## Development
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
npm ci
|
|
349
|
+
npm start # runs the demo application
|
|
350
|
+
npm run build # builds the library into dist/easy-mat-ui
|
|
351
|
+
npm test # runs the unit tests (headless Chrome)
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
## Contributing
|
|
355
|
+
|
|
356
|
+
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the
|
|
357
|
+
[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
|
|
358
|
+
|
|
359
|
+
## License
|
|
360
|
+
|
|
361
|
+
[MIT](LICENSE)
|