SCM Utils

Common tools and standalone components shared among Angular based web applications.

Platform

Angular 22 + Material

Entry points

La libreria non espone un barrel unico: l'entry point secondario e' l'unica unita' di code splitting riconosciuta da ng-packagr, quindi ogni gruppo di simboli che ha un ciclo di vita proprio vive nel suo entry point. Importare sempre dal path specifico.

| Livello | Entry point | Contenuto | Note | |---|---|---|---| | L0 | core | SystemUtils, models, definitions, pipe, direttive validator, servizi (broadcast, screen, theme, splash, environment) | nessuna dipendenza da Angular Material | | L0 | core.date | provideScmDateFns, MAT_DATE_FNS_FORMATS, abvLocalDateInterceptor | isola @angular/material/core + datepicker | | L0 | core.markdown | MarkdownUtils, FormatMarkdownPipe | parser markdown, fuori dal percorso comune | | L0 | core.validators | direttive validator per i form template-driven (ValidatorDirective, ValidIfDirective, EqualsValidatorDirective, PasswordValidatorDirective, EmailsValidatorDirective, ...) | isola @angular/forms (53 KB): core sta sul percorso di boot e non deve trascinarselo | | L0.5 | ui.shell | ShellService (info, error, busy*, wait, BusyTimer), ShellMessageComponent, ShellBusyComponent | zero Material e zero CDK: e' quello che shell, interceptor, guard e app initializer possono permettersi sul percorso di boot | | L1 | ui | FlexLayoutModule, MediaObserver, UIService, tipi dei dialog | kernel: deve restare magro, e non importa valori da Material | | L1 | ui.paginator | PaginatorIntl | isola @angular/material/paginator, che si porta dietro mat-select e mat-option | | L1.5 | ui.dialogs | DialogService (estende ShellService) + confirm, delete, toast, open, e le aperture pigre dei dialog pesanti | tutto cio' che chiede qualcosa all'utente, piu' il toast | | L2 | ui.dialogs.auth | credentials, reset-password, prompt-otp, OtpInputComponent, PasswordStrengthComponent | solo route di login/account | | L2 | ui.dialogs.prompt | prompt, prompt-date, prompt-time | porta @angular/material/datepicker | | L2 | ui.dialogs.select | select, select-tree, send-to | porta mat-tree, mat-list, mat-chips | | L2 | ui.files | file-input, file-preview, select-file, select-picture | | | L2 | ui.controls | button-selector, button-toggle, chips-selector | base Material comune: button, icon, form-field | | L2 | ui.controls.date | MatDatepickerParseErrorFixDirective, CalendarEmptyHeader | isola @angular/material/datepicker: ui.dialogs.prompt aggancia solo questo | | L2 | ui.controls.tree | TreePickerComponent | isola mat-tree, mat-tabs, mat-input, mat-checkbox, che nessun altro controllo usa | | L2 | ui.filters | FilterBarComponent + modello Filters | | | L2 | ui.navigation | NavigationBarComponent + definizioni | shell applicativa | | L2 | ui.tinymce | TinymceEditorDirective, TinymceLoaderService, TinymceUtils, TinyMceEditorComponent, langs/it.js | tinymce (caricato a runtime) |

Il peer dependency opzionale tinymce serve solo a chi importa ui.tinymce: e' dichiarato in peerDependenciesMeta.optional proprio perche' nessun altro entry point lo aggancia.

Grafo delle dipendenze statiche

core        core.date        core.markdown        core.validators        ui.paginator        ui.controls.date
 |    \
 |     ui.shell
 |        |
 ui ------|-------------------------------------------------------
 |        |      |               |             |             |                 |              |
 |        | ui.controls  ui.controls.tree  ui.filters  ui.navigation  ui.dialogs.select  ui.tinymce
 |        |
ui.dialogs      <-- DialogService extends ShellService: dipende da `ui` E da `ui.shell`
 |         |                  |              |
 |   ui.dialogs.auth   ui.dialogs.prompt  ui.files
 |
`ui.dialogs` --- import() --->  ui.dialogs.{auth,prompt,select}, ui.files

Gli archi dinamici puntano all'insu' e sono l'unica ragione per cui quei quattro entry point restano fuori dal bundle iniziale. Regge finche' NESSUNO di loro importa DialogService: per error() e busy() iniettano ShellService.

Regole da rispettare

1. Il grafo statico tra entry point deve restare un DAG: ui.dialogs raggiunge i dialog pesanti solo con import(), e quei quattro entry point non devono importare DialogService in nessun modo — ng-packagr rifiuta la build con circular dependency al primo che lo fa. Per messaggi e attesa iniettano ShellService, che sta sotto di loro nel grafo.
2. I tipi condivisi fra il facade e i dialog pesanti stanno in ui (dialog.definitions.ts). Se un tipo servisse a entrambi e vivesse nel dialog, l'import() del facade tornerebbe statico.
3. Il facade usa import type per i tipi dei componenti e import() per i valori: e' quello che tiene i dialog fuori dal bundle iniziale.
4. Dopo una modifica, verificare che gli import() sopravvivano alla build: grep -o "import('@fabio[^']*')" dist/scm-utils/fesm2022/*ui.dialogs.mjs deve stampare i nove.
5. ui.shell non importa nulla da @angular/material ne' da @angular/cdk, e nemmeno da ui. E' l'unica ragione per cui esiste: se ci finisce dentro un solo simbolo di Material, la shell torna a pagare l'intero stack sul percorso di boot. Da verificare dopo ogni build: grep -oE "@angular/(material|cdk)[^'\"]*" dist/scm-utils/fesm2022/*ui.shell.mjs non deve stampare nulla.
6. ui non importa valori da Material. PaginatorIntl e' uscito da li' proprio per questo: era l'unico simbolo che ne dipendeva, e faceva pagare mat-paginator + mat-select + mat-option a chiunque toccasse ui.dialogs. Restano due eccezioni, entrambe volute: MatFormFieldAppearance in dialog.definitions.ts, che e' un import type e quindi sparisce in compilazione, e @angular/cdk/layout (1 KB) di cui MediaObserver ha bisogno.
7. Le sovrapposizioni di ui.shell stanno nel top layer del browser, non nello stack del CDK. Da Angular CDK 22 ogni overlay viene aperto come popover="manual", quindi un dialog Material non sta piu' a z-index 1000: sta nel top layer, che viene disegnato sopra tutta la pagina qualunque cosa dica lo z-index della pagina. Un numero, per quanto alto, non ci arriva sopra: per questo ShellService promuove anche i suoi due overlay con showPopover(). Nel top layer l'ordine e' quello di promozione, l'ultimo promosso sta sopra. Da qui le tre regole esplicite: setBusy() ripromuove il messaggio dopo aver alzato il busy, DialogService.open() chiama raiseMessage() dopo aver aperto un dialog, e chiama clearBusy(true) senza periodo di grazia. La coppia --ars-shell-dialog-z-index/--ars-shell-busy-z-index (1100/1090) resta valida e serve ancora: e' quello che ordina gli overlay sui browser senza Popover API, dove nemmeno il CDK la usa. Se un'applicazione avesse bisogno del vecchio comportamento puo' spegnere la Popover API del CDK con { provide: OVERLAY_DEFAULT_CONFIG, useValue: { usePopover: false } }.

Da dove parte un'applicazione

core + ui.shell. Sono i due entry point che una applicazione carica comunque prima di avere una rotta, e gli unici due che non costano Material. core porta SystemUtils, i modelli, BroadcastService, SplashService, EnvironmentService, ThemeService; ui.shell porta il modo di dire all'utente che la sessione e' scaduta o che l'API non risponde.

La conseguenza pratica per chi scrive l'applicazione:

• shell, interceptor, guard, provideAppInitializer -> ShellService di ui.shell
• componenti di rotta -> DialogService di ui.dialogs, che apre anche i dialog pesanti

I tre servizi sono una catena, non tre servizi diversi:

ShellService                info, error, busy*, wait, busyTimer     ui.shell
  L DialogService           + open, confirm, delete, toast,         ui.dialogs
                              select, prompt, sendTo, ... (pigri)

Quindi chi inietta DialogService ha tutto quello che aveva prima: info, error e busy non sono spariti, sono ereditati. E non esistono in due copie: c'e' una implementazione sola, quella senza Material.

ShellService.info() e ShellService.error() hanno gli stessi parametri, nello stesso ordine, delle omonime di DialogService: spostare una chiamata dall'una all'altra e' un cambio di servizio iniettato e nient'altro.

Token CSS della shell

ui.shell ridisegna in CSS e SVG quello che Material gli darebbe: i colori passano da un token per ruolo, definito in styles/ui.colors.scss e sovrascrivibile dall'applicazione.

--ars-shell-dialog-background-color, --ars-shell-dialog-radius, --ars-shell-dialog-elevation, --ars-shell-dialog-scrim-color, --ars-shell-dialog-sunken-background-color, --ars-shell-busy-scrim-color, --ars-shell-busy-track-color, --ars-shell-busy-bare-color, --ars-shell-dialog-z-index, --ars-shell-busy-z-index.

I token vivono in tre posti: :root, @media (prefers-color-scheme: dark) e body.light/body.dark. L'ultima riga e' quella che conta quando l'utente forza un tema contro il sistema, ed e' anche il motivo per cui i componenti della shell leggono ThemeService invece di prefers-color-scheme.

Migrazione (da 22.5.x)

• info, error, busy, busySpinner, busyHourglass, wait, busyTimer e clearBusy sono passati a ShellService. DialogService li eredita, quindi nessuna chiamata cambia.
• info() e error() restituiscono ShellMessageRef invece di MatDialogRef<InfoDialogComponent>: close() e afterClosed() funzionano come prima, il resto di MatDialogRef no.
• clearBusy() accetta immediate: clearBusy(true) non aspetta i 500 ms di grazia.
• BusyTimer si importa da ui.shell, non piu' da ui.dialogs.
• InfoDialogComponent e BusyDialogComponent non esistono piu': li sostituiscono ShellMessageComponent e ShellBusyComponent, senza Material. Chi li importava direttamente (o ne passava il tipo a open()) deve cambiare.
• DialogService non estende piu' UIService: appearance e setAppearance() restano sulla stessa istanza di segnale del UIService di root, ma per delega. Chi si aspettava di ricevere un UIService iniettando DialogService deve iniettare UIService.
• PaginatorIntl non sta piu' in ui: sta in ui.paginator.
• ui.application non esiste piu': i nove metodi di ApplicationDialogService stanno in DialogService. Chi lo iniettava inietta DialogService.
• Le direttive validator non stanno piu' in core: stanno in core.validators.
• I token CSS della shell stanno tutti sotto --ars-shell-dialog-* e --ars-shell-busy-*: prima erano --ars-dialog-*, --ars-scrim-color, --ars-busy-* e --ars-progress-track-color, che si confondevano con --ars-dialog-item-*, cioe' i dialog Material veri. Un'applicazione che ne sovrascriveva qualcuno deve rinominarlo.

Authors

Fabio Buscaroli, Alberto Doria