@dflat-core/web

Librairies Angular de Dflat, empaquetées en un module npm unique (Angular Package Format, construit avec ng-packagr).

Points d'entrée

Ressources non TypeScript livrées dans le package :

• assets/ : styles partagés (site.scss, variables.scss, text.scss...), images et polices ;
• scss/ : styles globaux (dflat-app.scss, core-ux.scss, layout/default/default-layout.scss...).

Coquille applicative

system-ux fournit, en plus des écrans du module System, tout ce qui faisait auparavant l'ossature de l'application hôte (system-ux/src/lib/app) :

Le module racine d'une application se réduit alors à :

@NgModule({
    declarations: [AppComponent],
    imports: [DflatAppModule.forRoot(environment), routing],
    bootstrap: [AppComponent]
})
export class AppModule {}

environment implémente EnvironmentBase : URL de l'API, du hub et des fichiers, et, en option, appName, appLogoUrl et appVersion, affichés par la mise en page et la page d'accueil. Pour remplacer un service du socle (menus, permissions, intercepteur), il suffit de le fournir après DflatAppModule dans les providers du module racine.

La recherche globale n'interroge que les sources déclarées par l'application : une classe dérivée de DflatSearchProvider par famille d'objets, fournie en multi sous le jeton DFLAT_SEARCH_PROVIDERS.

Tester

yarn test                              # tous les *.spec.ts du package (Vitest, jsdom)
yarn vitest run core-ux                # un dossier ou un fichier
yarn tsc -p tsconfig.spec.json         # contrôle des types des tests

@dflat-core/web/core-ux/testing fournit la suite de test standard de BaseComponent :

describeBaseComponent('BaseCountryComponent', (app, route) => new TestCountryComponent(app, route), {
    entityKey: 'country', path: '/sys/country', title: 'Pays', permissionKey: 'system.country', requestsSections: true
});

Elle vérifie le contrat de BaseComponent sans rendre de gabarit : création dans un contexte d'injection, clé d'entité, lien, titre et permission, façade demandée au registre avec la clé de l'entité, ngOnInit (fil d'Ariane, chargement branché sur dataService.search, abonnement aux notifications, demande des onglets au registre EntitySections), Search / refresh, mise à jour sur notification, ngOnDestroy. Elle n'utilise que les fonctions globales de l'outil de test (describe, it, beforeEach, expect) et TestBed : elle ne dépend pas de l'outil. BaseComponentTestContext fournit les services du composant (vraies classes du socle, doublures pour DataService et Router).

• core-ux/src/lib/v2/components/base-component/base-component.spec.ts applique la suite à un composant minimal et teste les cas propres à la classe ;
• dflat -g ts génère, pour chaque composant Base<X>Component d'un module, <x>.component.generated.spec.ts (la même suite, avec les valeurs attendues du générateur) et, par module, <module>-components.generated.spec.ts (describeGeneratedModule : chaque composant a sa route, clés d'entité uniques, onglets des entités liées attendus par entité et pointant vers des entités et composants du module, éléments de menu vers une route existante et porteurs d'une permission du module).

Les onglets des entités liées (sections @relations des formulaires) sont déclarés pour tout le module par le service généré <Module>GeneratedSectionService (<module>-sections.generated.ts), seul fichier généré qui importe les composants des onglets. Le module Angular <module>-ux l'enregistre dans son constructeur, EntitySections.register(injector.get(<Module>GeneratedSectionService)), et Base<X>Component demande ses onglets par la clé de son entité (EntitySections.registerSections(this.getEntityKey(), this.facade)), sans importer d'autre composant : pas de dépendance circulaire entre composants. Le service n'est interrogé qu'une fois par entité : la définition des onglets est gardée dans le cache d'initialisation des écrans (InitCacheService, DataService.getCachedValue), comme les descripteurs de filtre et le filtre vide, et vidée avec eux ; l'enregistrement sur la façade est fait à chaque initialisation.

Dans le package, Vitest est lancé directement (vitest.config.mts, tools/vitest.setup.ts), sans angular.json : les décorateurs sont compilés en mode JIT et les gabarits remplacés par un gabarit vide. Une application lance les mêmes tests par sa cible test (@angular/build:unit-test, Vitest et jsdom), que le modèle dflat-webhost déclare (yarn test dans webapps). Les .spec.ts ne sont pas publiés ; seul le point d'entrée testing l'est.

Construire

yarn install
yarn build           # <dépôt>/artifacts/nodejs/dflat-web (compilation partielle, publiable)
yarn watch           # reconstruction continue pendant le développement
yarn run pack        # <dépôt>/artifacts/nodejs/dflat-web-<version>.tgz

Depuis la racine du dépôt, scripts/publish-dflat.ps1 enchaîne ces étapes :

.\scripts\publish-dflat.ps1 -bw                  # yarn install si besoin, build, vidage du cache Angular de webapps
.\scripts\publish-dflat.ps1 -pn                  # package versionné + archive .tgz (version calculée depuis npmjs.com)
.\scripts\publish-dflat.ps1 -pn -Push            # ... puis publication sur npmjs.com, après confirmation

yarn install applique tools/patch-ng-packagr.js : correctif d'un bug de ng-packagr 19.2 sur la réécriture des url() des partials Sass (voir le commentaire du script).

Utiliser dans un espace de travail Angular / Nx

1. Dépendance, dans package.json : la version publiée sur npmjs.com ("@dflat-core/web": "1.0.2"), cas de toute application, dont celles créées par dflat -newhost.

   webapps, dans le dépôt, n'en dépend pas : il compile les librairies depuis leurs sources, pour développer le package et l'application en même temps. Les chemins de webapps/tsconfig.json mènent à webapps/libs/dflat-web, une jonction par point d'entrée vers web/dflat-web :

   "@dflat-core/web": ["libs/dflat-web/src/index.ts"],
   "@dflat-core/web/*": ["libs/dflat-web/*/src/index.ts"]
   

   Les jonctions (non versionnées) sont créées par webapps/tools/check-dflat-web.js, lancé par yarn start et par dflat -r / dflat -rc. Elles sont individuelles : une seule jonction vers web/dflat-web ferait résoudre Angular dans web/dflat-web/node_modules (double instance). Toute modification d'un fichier du package (TypeScript, template, style) est recompilée par nx serve dans la foulée (quelques secondes), sans compiler dist ni vider le cache. L'application doit aussi installer les peerDependencies du package : les librairies Angular tierces qu'il utilise (ngx-toastr, ng-http-loader...). Le package ne dépend plus de Bootstrap : les styles de base et des classes de Bootstrap qu'il utilise sont dans ses assets (assets/components/bootstrap-lite.scss). Les icônes « fa fa- » n'utilisent plus font-awesome : ce sont des SVG des assets (assets/images/icons/fa, feuille assets/components/icons.scss). Le modèle dflat-webhost les liste déjà dans le package.json du front qu'il génère.

2. Dans les options de build de l'application (project.json) :

   "preserveSymlinks": true,
   "stylePreprocessorOptions": { "includePaths": ["node_modules", "node_modules/@dflat-core/web/assets"] },
   "assets": [{ "input": "node_modules/@dflat-core/web/assets", "glob": "*/**", "output": "assets" }]
   

   preserveSymlinks évite de résoudre Angular depuis web/dflat-web/node_modules (double instance). Les includePaths permettent à dflat-app.scss de résoudre les feuilles des assets du package.

3. Styles globaux (styles.scss) :

   @import "../../../node_modules/@dflat-core/web/scss/dflat-app.scss";
   

   dflat-app.scss enchaîne les variables, les styles de base et des classes de Bootstrap utilisées, avec le thème Pulse du package (assets/components/bootstrap-lite.scss, générée par tools/generate-bootstrap-lite.js à partir de Bootstrap 4, de assets/theme-variables.scss et de assets/theme.scss), core-ux.scss, site.scss et les règles de mise en page plein écran de la coquille. Une application qui utilise d'autres classes de Bootstrap installe bootstrap et importe ses parties après dflat-app.scss.

   Les feuilles de style tierces qui ne passent pas par Sass (toastr) restent dans le tableau styles des options de build.

Règles propres à une librairie

La compilation partielle d'Angular est plus stricte que celle d'une application :

• pas d'import par le barrel de sa propre librairie (@dflat-core/web/core-ux depuis core-ux) : utiliser un chemin relatif. Entre librairies, toujours passer par @dflat-core/web/<librairie> ;
• toute classe déclarée par un NgModule doit être exportée par le src/index.ts de sa librairie (NG3001) ;
• pas de cycle d'imports entre un composant et ce qu'utilise son template (NG3003). Pour casser un cycle : import type lorsque le symbole ne sert qu'au typage, ou un InjectionToken lorsqu'un type de composant est nécessaire à l'exécution (voir core-ux/src/lib/modals/dialog-component.tokens.ts, RowRefHost dans row-ref.directive.ts) ;
• pas de cycle d'imports entre une classe et sa classe parente, même indirect : chaque point d'entrée est aplati en un seul fichier et la classe fille pourrait y être émise avant la parente (Cannot access 'X' before initialization au démarrage de l'application). tools/check-bundles.js, lancé par npm run build, le détecte.

Code généré

codegenerator -ts -webpkg <dépôt>\web\dflat-web écrit les librairies Dflat (core-model, system-model, system-data) dans ce dossier et génère les imports en @dflat-core/web/<librairie>. Sans -webpkg (application hôte hors dépôt), ces librairies ne sont pas générées : elles sont fournies par le package. dbmanager écrit les permissions TypeScript du module System dans system-root/src/lib.