@arsedizioni/ars-utils 22.1.5 → 22.5.2

package/README.md

@@ -1,10 +1,158 @@
-# Ars Utils
-
-Common tools and components shared among Ars Edizioni Angular based web applications.
-
-## Platform
-
-Angular 9 + Material
-
-## Authors
-Fabio Buscaroli, Alberto Doria
+# ARS Utils
+
+Common tools and standalone components shared among ARS Edizioni Angular based web applications.
+
+Rispetto alla versione monolitica precedente adotta la struttura a entry point
+introdotta con `@fabio.buscaroli/scm-utils`: code splitting e tree shaking sono il criterio di
+ripartizione dei simboli, non un effetto collaterale.
+
+## 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.
+
+### Nucleo condiviso
+
+| Livello | Entry point | Contenuto | Note |
+|---|---|---|---|
+| L0 | `core` | `SystemUtils`, models, definitions, pipe, direttive validator, servizi (broadcast, screen, theme, splash, environment), `LoginOAuthType` | nessuna dipendenza da Angular Material |
+| L0 | `core.date` | `provideArsDateFns`, `provideArsLocalDates`, `MAT_DATE_FNS_FORMATS`, `arsLocalDateInterceptor`, `ARS_TIME_ZONE` | isola `@angular/material/core` + `datepicker` |
+| L0 | `core.markdown` | `MarkdownUtils`, `FormatMarkdownPipe` | parser markdown, fuori dal percorso comune |
+| 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 nulla 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` | tutto cio' che chiede qualcosa all'utente, piu' il toast |
+| L2 | `ui.dialogs.auth` | credentials, reset-password, recover-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, tree-picker, calendar-empty-header | |
+| L2 | `ui.filters` | `FilterBarComponent` + modello `Filters` | |
+| L2 | `ui.navigation` | `NavigationBarComponent` + definizioni | shell applicativa |
+| L3 | `ui.application` | `ApplicationDialogService` | facade: carica i dialog pesanti con `import()` |
+
+### Specifici ARS
+
+| Livello | Entry point | Contenuto | Dipendenze pesanti |
+|---|---|---|---|
+| L0.5 | `support.common` | `SupportService`, notifiche, definitions, messages | - |
+| L0.5 | `evolution.common` | `EvolutionService`, account, compliance, login, interceptor auth | - |
+| L2 | `ui.oauth` | `LoginOAuthComponent`, `LoginOAuthOkMSComponent` | `@azure/msal-angular`, `@azure/msal-browser` |
+| L2 | `ui.help` | `HelpService`, `HelpViewerComponent`, modello dei capitoli | - |
+| L2 | `ui.tinymce` | `TinymceUtils`, `FullScreenEditorComponent`, `langs/it.js` | `tinymce`, `@tinymce/tinymce-angular` |
+| L2 | `ui.notifications` | `NotificationsBrowserComponent` (ex `support.ui`) | - |
+| L2 | `clipper.common` | `ClipperService`, archive, calendar, collaboration, documents, login, note, interceptor auth | - |
+| L4 | `clipper.ui` | browser, document, note, references, search-* e `ClipperDocumentsUtils` | `clipper.scss` |
+
+I peer dependency opzionali (`@azure/msal-*`, `tinymce`, `@tinymce/tinymce-angular`) servono
+solo a chi importa rispettivamente `ui.oauth` e `ui.tinymce`: sono dichiarati in
+`peerDependenciesMeta.optional` proprio perche' nessun altro entry point li aggancia.
+
+### Grafo delle dipendenze statiche
+
+```
+core          core.date        core.markdown        ui.paginator
+ |    \
+ |     ui.shell
+ |        |
+ ui ------|-----------------------------------------------------------
+ |        |   |            |            |                  |          |
+ |        | ui.controls ui.filters ui.navigation  ui.dialogs.select  clipper.common
+ |        |
+ui.dialogs      <-- DialogService extends ShellService: dipende da `ui` E da `ui.shell`
+ |         |                  |              |          |            |
+ |   ui.dialogs.auth   ui.dialogs.prompt  ui.files   ui.help    ui.oauth
+ |                                                   ui.notifications (+ support.common)
+ui.application  --- import() --->  ui.dialogs.{auth,prompt,select}, ui.files
+ |
+clipper.ui  (+ clipper.common, ui.controls, ui.files, ui.dialogs.select)
+```
+
+`evolution.common` e `support.common` dipendono solo da `core`.
+
+### Regole da rispettare
+
+1. Il grafo tra entry point deve restare un DAG. Un entry point di livello L2 non puo'
+   importare `ui.application`, ne' un entry point puo' importare se stesso per package path
+   (ng-packagr lo segnala come `circular dependency on itself`).
+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('@arsedizioni[^']*')" dist/ars-utils/fesm2022/*ui.application.mjs`
+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/ars-utils/fesm2022/*ui.shell.mjs` non deve
+   stampare nulla.
+7. Le sovrapposizioni di `ui.shell` non stanno nello stack del CDK, quindi il loro ordine e' un
+   z-index fisso: `cdk-overlay-container` sta a 1000, il busy a 1090 e il messaggio a 1100. Un
+   errore che esce mentre un dialog Material e' aperto deve stargli sopra, ed e' cosi'. L'unico
+   caso che un numero fisso non sa esprimere e un dialog aperto mentre il busy e ancora su:
+   per questo `DialogService.open()` chiama `clearBusy(true)`, senza periodo di grazia.
+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.
+
+### Da dove parte un'applicazione
+
+`core` + `ui.shell`. Sono i due entry point che una applicazione ARS 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.
+
+Non sono un entry point solo, e non devono diventarlo: `core` e' L0 e ci dipendono anche
+`clipper.common`, `evolution.common` e `support.common`, che di interfaccia non ne hanno. Fonderli
+significherebbe far dipendere tre entry point headless da uno di UI, cioe' rompere la regola 1.
+
+La conseguenza pratica per chi scrive l'applicazione:
+
+- shell, interceptor, guard, `provideAppInitializer` -> `ShellService` di `ui.shell`
+- componenti di rotta -> `DialogService` di `ui.dialogs`, e `ApplicationDialogService` di `ui.application` per i dialog pesanti
+
+I tre servizi sono una catena, non tre servizi diversi:
+
+```
+ShellService                info, error, busy*, wait, busyTimer     ui.shell
+  └ DialogService           + open, confirm, delete, toast          ui.dialogs
+      └ ApplicationDialogService  + select, prompt, sendTo, ...     ui.application
+```
+
+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.
+
+## Differenze rispetto alla versione precedente (22.1.x monolitica)
+
+- Nessun barrel radice: `@arsedizioni/ars-utils` esporta solo `ARS_UTILS_VERSION`.
+- `ui` non contiene piu' i dialog: `DialogService` sta in `ui.dialogs`.
+- `ui.application` resta il solo facade e non riesporta piu' componenti: i controlli sono in
+  `ui.controls`, i file in `ui.files`, i filtri in `ui.filters`, la navigazione in `ui.navigation`.
+- `SystemUtils.markdownToHtml` non esiste piu': usare `MarkdownUtils.toHtml` da `core.markdown`.
+- `SelectableModel` espone `first` e `selectedAny` al posto di `selectedFirst` e `selectedAll`.
+- `support.ui` si chiama `ui.notifications`, `help` si chiama `ui.help`, `tinymce` si chiama `ui.tinymce`.
+- `PaginatorIntl` non sta piu' in `ui`: sta in `ui.paginator`.
+- La shell non deve piu' iniettare `DialogService` per mostrare un errore: c'e' `ShellService` in `ui.shell`.
+- `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>`.
+  In myARS nessun chiamante usava quel valore; controllare nelle altre applicazioni.
+- `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.
+
+## Authors
+Fabio Buscaroli, Alberto Doria