@arsedizioni/ars-utils 22.0.33 → 22.0.35

package/clipper.common/README.md

@@ -1,74 +1,74 @@
-# Clipper common — Vitest test suite
-
-Effective unit-test suite for the `clipper.common` library: the 6 feature services,
-the shared `ClipperCoreService`, the `ClipperService` facade and `ClipperAuthInterceptor`.
-
-## What is covered
-
-| Spec | Focus |
-| --- | --- |
-| `core.service.spec.ts` | state mutators (`ensureLoginInfo`, `setLoggedIn`, `setTeams`, `updateContext`, `initializeChannels`, `reset`, `clear`), lazy `loginInfo` load, `initialize` (serviceUri/appUri/flags, client-id / embedded, F5 branch), broadcast handlers (`LOGIN_CHANGED`, `LOGOUT` logged-in/out), `ping` |
-| `login.service.spec.ts` | credential + OAuth login, MFA pending, failure, temporary context, `autoLogin`/`autoLogout`, `confirmIdentity`, `logout` (clears session on success **and** error), `newOTP` |
-| `documents.service.spec.ts` | every endpoint, `references`/`referencesFacets` mode routing + `null`, default taxonomy body, dashboard counters, bag parsing (`loadBag`/`addToBag`/`removeFromBag`/`clearBag`) |
-| `account.service.spec.ts` | password/settings, `updateSettings`→`setChannels`, `updateChannelsState`→`setChannelsState`, the moved channel helpers, `updateTrialInfo` guards + both result branches, links |
-| `archive.service.spec.ts` | folders/files endpoints, `exportArchiveFolders` URL building, multipart `importArchiveFolders`/`saveArchiveFile` form data, blob download |
-| `calendar.service.spec.ts` | all deadline endpoints + team storage + ICS export |
-| `collaboration.service.spec.ts` | teams (incl. `adminsOnly` team-storage rule), contacts, notes |
-| `clipper.service.spec.ts` | facade exposes/forwards feature services, re-exports core signals by identity, delegates `initialize`/`ping` |
-| `auth.interceptor.spec.ts` | header decoration, passthrough of non-Clipper URLs, error mapping (0/403/405/410/5xx), `NotifySystemErrors` flag, 5s debounce |
-
-## File placement
-
-Drop the files into the library mirroring its structure (import paths assume this):
-
-```
-common/
-  services/   ← *.service.spec.ts + clipper.service.spec.ts
-  interceptors/ auth.interceptor.spec.ts
-  testing/    ← clipper-test-helpers.ts   (shared TestBed harness + fakes)
-```
-
-`vitest.config.ts` goes at the package root and `src/test-setup.ts` wherever your
-setup lives — adjust `setupFiles` accordingly. If you already have a Vitest config,
-just merge the `test` block.
-
-## Running
-
-```bash
-npm i -D vitest @analogjs/vite-plugin-angular @analogjs/vitest-angular jsdom
-npx vitest run            # single run
-npx vitest                # watch
-npx vitest run --coverage # coverage
-```
-
-`@angular/*` and `@arsedizioni/ars-utils/*` are the library's own dependencies and
-are used as-is (no mocking). Only `BroadcastService` and `SplashService` are replaced
-by controllable test doubles via TestBed providers.
-
-## How it works
-
-`createHarness()` (in `testing/clipper-test-helpers.ts`) wires a `TestBed` with the
-HTTP testing backend (`HttpTestingController`), all services and the fakes, resets
-storage, and (unless `skipInitialize`) calls `core.initialize()`. It returns every
-service plus the fakes, so a spec reads like:
-
-```ts
-const h = createHarness();
-h.documents.query({ text: 'iva' }).subscribe();
-h.http.expectOne(`${h.serviceUri}/documents`).flush(ok({ items: [] }));
-```
-
-`FakeBroadcastService.emit(id, data)` pushes inbound bus messages (for the core
-broadcast handler), while `sendMessage` is a spy recording outbound broadcasts —
-the two are decoupled to avoid feedback loops.
-
-## Assumptions / notes
-
-- `@Service()` is treated as `@Injectable()`-compatible (it is provided through TestBed).
-- The suite was authored against the library sources but **not executed here**, because
-  the private `@arsedizioni` packages and the Angular toolchain aren't installed in the
-  authoring environment. Run `vitest` in the repo; if `@Service`/zoneless setup needs a
-  tweak, it will be in `src/test-setup.ts` only.
-- `initializeChannels`/`updateChannels` mutate the shared `ClipperChannels` constant
-  objects (existing library behaviour) — assertions check the produced channel, not
-  object identity, to stay robust.
+# Clipper common — Vitest test suite
+
+Effective unit-test suite for the `clipper.common` library: the 6 feature services,
+the shared `ClipperCoreService`, the `ClipperService` facade and `ClipperAuthInterceptor`.
+
+## What is covered
+
+| Spec | Focus |
+| --- | --- |
+| `core.service.spec.ts` | state mutators (`ensureLoginInfo`, `setLoggedIn`, `setTeams`, `updateContext`, `initializeChannels`, `reset`, `clear`), lazy `loginInfo` load, `initialize` (serviceUri/appUri/flags, client-id / embedded, F5 branch), broadcast handlers (`LOGIN_CHANGED`, `LOGOUT` logged-in/out), `ping` |
+| `login.service.spec.ts` | credential + OAuth login, MFA pending, failure, temporary context, `autoLogin`/`autoLogout`, `confirmIdentity`, `logout` (clears session on success **and** error), `newOTP` |
+| `documents.service.spec.ts` | every endpoint, `references`/`referencesFacets` mode routing + `null`, default taxonomy body, dashboard counters, bag parsing (`loadBag`/`addToBag`/`removeFromBag`/`clearBag`) |
+| `account.service.spec.ts` | password/settings, `updateSettings`→`setChannels`, `updateChannelsState`→`setChannelsState`, the moved channel helpers, `updateTrialInfo` guards + both result branches, links |
+| `archive.service.spec.ts` | folders/files endpoints, `exportArchiveFolders` URL building, multipart `importArchiveFolders`/`saveArchiveFile` form data, blob download |
+| `calendar.service.spec.ts` | all deadline endpoints + team storage + ICS export |
+| `collaboration.service.spec.ts` | teams (incl. `adminsOnly` team-storage rule), contacts, notes |
+| `clipper.service.spec.ts` | facade exposes/forwards feature services, re-exports core signals by identity, delegates `initialize`/`ping` |
+| `auth.interceptor.spec.ts` | header decoration, passthrough of non-Clipper URLs, error mapping (0/403/405/410/5xx), `NotifySystemErrors` flag, 5s debounce |
+
+## File placement
+
+Drop the files into the library mirroring its structure (import paths assume this):
+
+```
+common/
+  services/   ← *.service.spec.ts + clipper.service.spec.ts
+  interceptors/ auth.interceptor.spec.ts
+  testing/    ← clipper-test-helpers.ts   (shared TestBed harness + fakes)
+```
+
+`vitest.config.ts` goes at the package root and `src/test-setup.ts` wherever your
+setup lives — adjust `setupFiles` accordingly. If you already have a Vitest config,
+just merge the `test` block.
+
+## Running
+
+```bash
+npm i -D vitest @analogjs/vite-plugin-angular @analogjs/vitest-angular jsdom
+npx vitest run            # single run
+npx vitest                # watch
+npx vitest run --coverage # coverage
+```
+
+`@angular/*` and `@arsedizioni/ars-utils/*` are the library's own dependencies and
+are used as-is (no mocking). Only `BroadcastService` and `SplashService` are replaced
+by controllable test doubles via TestBed providers.
+
+## How it works
+
+`createHarness()` (in `testing/clipper-test-helpers.ts`) wires a `TestBed` with the
+HTTP testing backend (`HttpTestingController`), all services and the fakes, resets
+storage, and (unless `skipInitialize`) calls `core.initialize()`. It returns every
+service plus the fakes, so a spec reads like:
+
+```ts
+const h = createHarness();
+h.documents.query({ text: 'iva' }).subscribe();
+h.http.expectOne(`${h.serviceUri}/documents`).flush(ok({ items: [] }));
+```
+
+`FakeBroadcastService.emit(id, data)` pushes inbound bus messages (for the core
+broadcast handler), while `sendMessage` is a spy recording outbound broadcasts —
+the two are decoupled to avoid feedback loops.
+
+## Assumptions / notes
+
+- `@Service()` is treated as `@Injectable()`-compatible (it is provided through TestBed).
+- The suite was authored against the library sources but **not executed here**, because
+  the private `@arsedizioni` packages and the Angular toolchain aren't installed in the
+  authoring environment. Run `vitest` in the repo; if `@Service`/zoneless setup needs a
+  tweak, it will be in `src/test-setup.ts` only.
+- `initializeChannels`/`updateChannels` mutate the shared `ClipperChannels` constant
+  objects (existing library behaviour) — assertions check the produced channel, not
+  object identity, to stay robust.