@dflat-core/web 1.0.10 → 1.0.11

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.
Files changed (2) hide show
  1. package/README.md +157 -157
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,157 +1,157 @@
1
- # @dflat-core/web
2
-
3
- Librairies Angular de Dflat, empaquetées en un module npm unique (Angular Package Format, construit avec ng-packagr).
4
-
5
- ## Points d'entrée
6
-
7
- | Import | Contenu |
8
- | -------------------------- | ------------------------------------------------------------ |
9
- | `@dflat-core/web/core` | Utilitaires, `EnvironmentBase` |
10
- | `@dflat-core/web/core-model` | Modèle de base (interfaces générées depuis Dflat.Kernel.Model) |
11
- | `@dflat-core/web/core-services` | Authentification, messages, menus, hub SignalR... |
12
- | `@dflat-core/web/core-data` | `DataService`, `EntityDataService` |
13
- | `@dflat-core/web/core-ux` | Composants, directives et services d'interface |
14
- | `@dflat-core/web/system-model` | Modèle du module System (généré) |
15
- | `@dflat-core/web/system-data` | Services de données du module System (générés) |
16
- | `@dflat-core/web/system-root` | Permissions, clés d'entités et menus du module System |
17
- | `@dflat-core/web/system-ux` | Écrans du module System, et la coquille applicative |
18
-
19
- Ressources non TypeScript livrées dans le package :
20
-
21
- - `assets/` : styles partagés (`site.scss`, `variables.scss`, `text.scss`...), images et polices ;
22
- - `scss/` : styles globaux (`dflat-app.scss`, `core-ux.scss`, `layout/default/default-layout.scss`...).
23
-
24
- ## Coquille applicative
25
-
26
- `system-ux` fournit, en plus des écrans du module System, tout ce qui faisait auparavant
27
- l'ossature de l'application hôte (`system-ux/src/lib/app`) :
28
-
29
- | Symbole | Rôle |
30
- | --------------------------------------------------------- | ----------------------------------------------------------- |
31
- | `DflatAppModule` | Socle du module racine : modules Angular et tiers, intercepteur HTTP, permissions, menus, langue |
32
- | `DFlatLayoutComponent` | Mise en page : barre supérieure, menu latéral, contenu |
33
- | `HomepageComponent`, `SearchComponent`, `SearchResultComponent` | Accueil et recherche globale |
34
- | `UserMenuComponent`, `UserProfileComponent` | Menu et profil de l'utilisateur |
35
- | `AccessDeniedComponent`, `HistoryComponent`, `DFlatSpinnerComponent` | Écrans et composants utilitaires |
36
- | `DflatAppService` | Nom, logo et version de l'application (`EnvironmentBase`) |
37
- | `DFlatAuthInterceptor`, `DFlatPermissionService` | Implémentations par défaut, dérivables |
38
-
39
- Le module racine d'une application se réduit alors à :
40
-
41
- ```ts
42
- @NgModule({
43
- declarations: [AppComponent],
44
- imports: [DflatAppModule.forRoot(environment), routing],
45
- bootstrap: [AppComponent]
46
- })
47
- export class AppModule {}
48
- ```
49
-
50
- `environment` implémente `EnvironmentBase` : URL de l'API, du hub et des fichiers, et, en
51
- option, `appName`, `appLogoUrl` et `appVersion`, affichés par la mise en page et la page
52
- d'accueil. Pour remplacer un service du socle (menus, permissions, intercepteur), il suffit
53
- de le fournir après `DflatAppModule` dans les `providers` du module racine.
54
-
55
- La recherche globale n'interroge que les sources déclarées par l'application : une classe
56
- dérivée de `DflatSearchProvider` par famille d'objets, fournie en `multi` sous le jeton
57
- `DFLAT_SEARCH_PROVIDERS`.
58
-
59
- ## Construire
60
-
61
- ```bash
62
- npm install
63
- npm run build # <dépôt>/artifacts/nodejs/dflat-web (compilation partielle, publiable)
64
- npm run watch # reconstruction continue pendant le développement
65
- npm run pack # <dépôt>/artifacts/nodejs/dflat-web-<version>.tgz
66
- ```
67
-
68
- Depuis la racine du dépôt, `scripts/publish-dflat.ps1` enchaîne ces étapes :
69
-
70
- ```powershell
71
- .\scripts\publish-dflat.ps1 -bw # npm install si besoin, build, vidage du cache Angular de webapps
72
- .\scripts\publish-dflat.ps1 -pn # package versionné + archive .tgz (version calculée depuis npmjs.com)
73
- .\scripts\publish-dflat.ps1 -pn -Push # ... puis publication sur npmjs.com, après confirmation
74
- ```
75
-
76
- `npm install` applique `tools/patch-ng-packagr.js` : correctif d'un bug de ng-packagr 19.2 sur la réécriture
77
- des `url()` des partials Sass (voir le commentaire du script).
78
-
79
- ## Utiliser dans un espace de travail Angular / Nx
80
-
81
- 1. Dépendance, dans `package.json` : la version publiée sur npmjs.com
82
- (`"@dflat-core/web": "1.0.2"`), cas de toute application, dont celles créées par
83
- `dflat -newhost`.
84
-
85
- `webapps`, dans le dépôt, référence au contraire le dossier de sortie de ng-packagr, pour
86
- développer le package et l'application en même temps :
87
-
88
- ```json
89
- "@dflat-core/web": "file:../web/dflat-web/dist"
90
- ```
91
-
92
- `npm install` en fait un lien symbolique (`node_modules/@dflat-core/web` → `web/dflat-web/dist`) :
93
- `dist` doit donc exister, produit une fois par `npm run build:dev` ou `npm run watch`. Pour
94
- travailler, deux consoles :
95
-
96
- ```bash
97
- npm run watch:dflat-web # depuis webapps : ng-packagr --watch sur web/dflat-web
98
- npm start # depuis webapps : nx serve
99
- ```
100
-
101
- Toute modification d'un fichier du package (TypeScript, template, style) est recompilée par
102
- ng-packagr dans `dist`, et `nx serve` la reprend dans la foulée (quelques secondes), sans
103
- vider le cache ni relancer le serveur.
104
-
105
- L'application doit aussi installer les `peerDependencies` du package : les librairies
106
- Angular tierces qu'il utilise (`ngx-bootstrap`, `@swimlane/ngx-datatable`, `ngx-toastr`,
107
- `ng-http-loader`...) et les feuilles de style dont dépendent ses assets (`bootstrap`,
108
- `bootswatch`, `font-awesome`). Le modèle `dflat-webhost` les liste déjà dans le
109
- `package.json` du front qu'il génère.
110
-
111
- 2. Dans les options de build de l'application (`project.json`) :
112
-
113
- ```json
114
- "preserveSymlinks": true,
115
- "stylePreprocessorOptions": { "includePaths": ["node_modules", "node_modules/@dflat-core/web/assets"] },
116
- "assets": [{ "input": "node_modules/@dflat-core/web/assets", "glob": "*/**", "output": "assets" }]
117
- ```
118
-
119
- `preserveSymlinks` évite de résoudre Angular depuis `web/dflat-web/node_modules` (double instance).
120
- `node_modules` dans les `includePaths` permet à `dflat-app.scss` de résoudre Bootstrap et son thème.
121
-
122
- 3. Styles globaux (`styles.scss`) :
123
-
124
- ```scss
125
- @import "../../../node_modules/@dflat-core/web/scss/dflat-app.scss";
126
- ```
127
-
128
- `dflat-app.scss` enchaîne les variables, Bootstrap, le thème Bootswatch, `core-ux.scss`,
129
- `site.scss` et les règles de mise en page plein écran de la coquille. Pour un autre thème,
130
- ne l'importez pas : reprenez son contenu dans l'application en changeant la ligne
131
- `bootswatch`.
132
-
133
- Les feuilles de style tierces qui ne passent pas par Sass (toastr, ngx-datatable,
134
- bs-datepicker, font-awesome) restent dans le tableau `styles` des options de build.
135
-
136
- ## Règles propres à une librairie
137
-
138
- La compilation partielle d'Angular est plus stricte que celle d'une application :
139
-
140
- - **pas d'import par le barrel de sa propre librairie** (`@dflat-core/web/core-ux` depuis core-ux) : utiliser un
141
- chemin relatif. Entre librairies, toujours passer par `@dflat-core/web/<librairie>` ;
142
- - **toute classe déclarée par un NgModule doit être exportée** par le `src/index.ts` de sa librairie (NG3001) ;
143
- - **pas de cycle d'imports entre un composant et ce qu'utilise son template** (NG3003). Pour casser un cycle :
144
- `import type` lorsque le symbole ne sert qu'au typage, ou un `InjectionToken` lorsqu'un type de composant
145
- est nécessaire à l'exécution (voir `core-ux/src/lib/modals/dialog-component.tokens.ts`,
146
- `RowRefHost` dans `row-ref.directive.ts`) ;
147
- - **pas de cycle d'imports entre une classe et sa classe parente**, même indirect : chaque point d'entrée est
148
- aplati en un seul fichier et la classe fille pourrait y être émise avant la parente
149
- (`Cannot access 'X' before initialization` au démarrage de l'application). `tools/check-bundles.js`, lancé par
150
- `npm run build`, le détecte.
151
-
152
- ## Code généré
153
-
154
- `codegenerator -ts -webpkg <dépôt>\web\dflat-web` écrit les librairies Dflat (core-model, system-model,
155
- system-data) dans ce dossier et génère les imports en `@dflat-core/web/<librairie>`. Sans `-webpkg` (application hôte
156
- hors dépôt), ces librairies ne sont pas générées : elles sont fournies par le package. `dbmanager` écrit les
157
- permissions TypeScript du module System dans `system-root/src/lib`.
1
+ # @dflat-core/web
2
+
3
+ Librairies Angular de Dflat, empaquetées en un module npm unique (Angular Package Format, construit avec ng-packagr).
4
+
5
+ ## Points d'entrée
6
+
7
+ | Import | Contenu |
8
+ | -------------------------- | ------------------------------------------------------------ |
9
+ | `@dflat-core/web/core` | Utilitaires, `EnvironmentBase` |
10
+ | `@dflat-core/web/core-model` | Modèle de base (interfaces générées depuis Dflat.Kernel.Model) |
11
+ | `@dflat-core/web/core-services` | Authentification, messages, menus, hub SignalR... |
12
+ | `@dflat-core/web/core-data` | `DataService`, `EntityDataService` |
13
+ | `@dflat-core/web/core-ux` | Composants, directives et services d'interface |
14
+ | `@dflat-core/web/system-model` | Modèle du module System (généré) |
15
+ | `@dflat-core/web/system-data` | Services de données du module System (générés) |
16
+ | `@dflat-core/web/system-root` | Permissions, clés d'entités et menus du module System |
17
+ | `@dflat-core/web/system-ux` | Écrans du module System, et la coquille applicative |
18
+
19
+ Ressources non TypeScript livrées dans le package :
20
+
21
+ - `assets/` : styles partagés (`site.scss`, `variables.scss`, `text.scss`...), images et polices ;
22
+ - `scss/` : styles globaux (`dflat-app.scss`, `core-ux.scss`, `layout/default/default-layout.scss`...).
23
+
24
+ ## Coquille applicative
25
+
26
+ `system-ux` fournit, en plus des écrans du module System, tout ce qui faisait auparavant
27
+ l'ossature de l'application hôte (`system-ux/src/lib/app`) :
28
+
29
+ | Symbole | Rôle |
30
+ | --------------------------------------------------------- | ----------------------------------------------------------- |
31
+ | `DflatAppModule` | Socle du module racine : modules Angular et tiers, intercepteur HTTP, permissions, menus, langue |
32
+ | `DFlatLayoutComponent` | Mise en page : barre supérieure, menu latéral, contenu |
33
+ | `HomepageComponent`, `SearchComponent`, `SearchResultComponent` | Accueil et recherche globale |
34
+ | `UserMenuComponent`, `UserProfileComponent` | Menu et profil de l'utilisateur |
35
+ | `AccessDeniedComponent`, `HistoryComponent`, `DFlatSpinnerComponent` | Écrans et composants utilitaires |
36
+ | `DflatAppService` | Nom, logo et version de l'application (`EnvironmentBase`) |
37
+ | `DFlatAuthInterceptor`, `DFlatPermissionService` | Implémentations par défaut, dérivables |
38
+
39
+ Le module racine d'une application se réduit alors à :
40
+
41
+ ```ts
42
+ @NgModule({
43
+ declarations: [AppComponent],
44
+ imports: [DflatAppModule.forRoot(environment), routing],
45
+ bootstrap: [AppComponent]
46
+ })
47
+ export class AppModule {}
48
+ ```
49
+
50
+ `environment` implémente `EnvironmentBase` : URL de l'API, du hub et des fichiers, et, en
51
+ option, `appName`, `appLogoUrl` et `appVersion`, affichés par la mise en page et la page
52
+ d'accueil. Pour remplacer un service du socle (menus, permissions, intercepteur), il suffit
53
+ de le fournir après `DflatAppModule` dans les `providers` du module racine.
54
+
55
+ La recherche globale n'interroge que les sources déclarées par l'application : une classe
56
+ dérivée de `DflatSearchProvider` par famille d'objets, fournie en `multi` sous le jeton
57
+ `DFLAT_SEARCH_PROVIDERS`.
58
+
59
+ ## Construire
60
+
61
+ ```bash
62
+ yarn install
63
+ yarn build # <dépôt>/artifacts/nodejs/dflat-web (compilation partielle, publiable)
64
+ yarn watch # reconstruction continue pendant le développement
65
+ yarn run pack # <dépôt>/artifacts/nodejs/dflat-web-<version>.tgz
66
+ ```
67
+
68
+ Depuis la racine du dépôt, `scripts/publish-dflat.ps1` enchaîne ces étapes :
69
+
70
+ ```powershell
71
+ .\scripts\publish-dflat.ps1 -bw # yarn install si besoin, build, vidage du cache Angular de webapps
72
+ .\scripts\publish-dflat.ps1 -pn # package versionné + archive .tgz (version calculée depuis npmjs.com)
73
+ .\scripts\publish-dflat.ps1 -pn -Push # ... puis publication sur npmjs.com, après confirmation
74
+ ```
75
+
76
+ `yarn install` applique `tools/patch-ng-packagr.js` : correctif d'un bug de ng-packagr 19.2 sur la réécriture
77
+ des `url()` des partials Sass (voir le commentaire du script).
78
+
79
+ ## Utiliser dans un espace de travail Angular / Nx
80
+
81
+ 1. Dépendance, dans `package.json` : la version publiée sur npmjs.com
82
+ (`"@dflat-core/web": "1.0.2"`), cas de toute application, dont celles créées par
83
+ `dflat -newhost`.
84
+
85
+ `webapps`, dans le dépôt, référence au contraire le dossier de sortie de ng-packagr, pour
86
+ développer le package et l'application en même temps :
87
+
88
+ ```json
89
+ "@dflat-core/web": "link:../web/dflat-web/dist"
90
+ ```
91
+
92
+ `yarn install` en fait un lien symbolique (`node_modules/@dflat-core/web` → `web/dflat-web/dist`) :
93
+ `dist` doit donc exister, produit une fois par `yarn build:dev` ou `yarn watch`. Pour
94
+ travailler, deux consoles :
95
+
96
+ ```bash
97
+ yarn watch:dflat-web # depuis webapps : ng-packagr --watch sur web/dflat-web
98
+ yarn start # depuis webapps : nx serve
99
+ ```
100
+
101
+ Toute modification d'un fichier du package (TypeScript, template, style) est recompilée par
102
+ ng-packagr dans `dist`, et `nx serve` la reprend dans la foulée (quelques secondes), sans
103
+ vider le cache ni relancer le serveur.
104
+
105
+ L'application doit aussi installer les `peerDependencies` du package : les librairies
106
+ Angular tierces qu'il utilise (`ngx-bootstrap`, `@swimlane/ngx-datatable`, `ngx-toastr`,
107
+ `ng-http-loader`...) et les feuilles de style dont dépendent ses assets (`bootstrap`,
108
+ `bootswatch`, `font-awesome`). Le modèle `dflat-webhost` les liste déjà dans le
109
+ `package.json` du front qu'il génère.
110
+
111
+ 2. Dans les options de build de l'application (`project.json`) :
112
+
113
+ ```json
114
+ "preserveSymlinks": true,
115
+ "stylePreprocessorOptions": { "includePaths": ["node_modules", "node_modules/@dflat-core/web/assets"] },
116
+ "assets": [{ "input": "node_modules/@dflat-core/web/assets", "glob": "*/**", "output": "assets" }]
117
+ ```
118
+
119
+ `preserveSymlinks` évite de résoudre Angular depuis `web/dflat-web/node_modules` (double instance).
120
+ `node_modules` dans les `includePaths` permet à `dflat-app.scss` de résoudre Bootstrap et son thème.
121
+
122
+ 3. Styles globaux (`styles.scss`) :
123
+
124
+ ```scss
125
+ @import "../../../node_modules/@dflat-core/web/scss/dflat-app.scss";
126
+ ```
127
+
128
+ `dflat-app.scss` enchaîne les variables, Bootstrap, le thème Bootswatch, `core-ux.scss`,
129
+ `site.scss` et les règles de mise en page plein écran de la coquille. Pour un autre thème,
130
+ ne l'importez pas : reprenez son contenu dans l'application en changeant la ligne
131
+ `bootswatch`.
132
+
133
+ Les feuilles de style tierces qui ne passent pas par Sass (toastr, ngx-datatable,
134
+ bs-datepicker, font-awesome) restent dans le tableau `styles` des options de build.
135
+
136
+ ## Règles propres à une librairie
137
+
138
+ La compilation partielle d'Angular est plus stricte que celle d'une application :
139
+
140
+ - **pas d'import par le barrel de sa propre librairie** (`@dflat-core/web/core-ux` depuis core-ux) : utiliser un
141
+ chemin relatif. Entre librairies, toujours passer par `@dflat-core/web/<librairie>` ;
142
+ - **toute classe déclarée par un NgModule doit être exportée** par le `src/index.ts` de sa librairie (NG3001) ;
143
+ - **pas de cycle d'imports entre un composant et ce qu'utilise son template** (NG3003). Pour casser un cycle :
144
+ `import type` lorsque le symbole ne sert qu'au typage, ou un `InjectionToken` lorsqu'un type de composant
145
+ est nécessaire à l'exécution (voir `core-ux/src/lib/modals/dialog-component.tokens.ts`,
146
+ `RowRefHost` dans `row-ref.directive.ts`) ;
147
+ - **pas de cycle d'imports entre une classe et sa classe parente**, même indirect : chaque point d'entrée est
148
+ aplati en un seul fichier et la classe fille pourrait y être émise avant la parente
149
+ (`Cannot access 'X' before initialization` au démarrage de l'application). `tools/check-bundles.js`, lancé par
150
+ `npm run build`, le détecte.
151
+
152
+ ## Code généré
153
+
154
+ `codegenerator -ts -webpkg <dépôt>\web\dflat-web` écrit les librairies Dflat (core-model, system-model,
155
+ system-data) dans ce dossier et génère les imports en `@dflat-core/web/<librairie>`. Sans `-webpkg` (application hôte
156
+ hors dépôt), ces librairies ne sont pas générées : elles sont fournies par le package. `dbmanager` écrit les
157
+ permissions TypeScript du module System dans `system-root/src/lib`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dflat-core/web",
3
- "version": "1.0.10",
3
+ "version": "1.0.11",
4
4
  "description": "Librairies Angular Dflat (core, core-*, system-*) et assets partagés, empaquetées en un module npm unique.",
5
5
  "license": "MIT",
6
6
  "peerDependencies": {