@arsedizioni/ars-utils 22.6.75 → 22.6.77

package/types/arsedizioni-ars-utils-core.date.d.ts

@@ -213,23 +213,36 @@ declare const DEFAULT_TIME_ZONE = "Europe/Rome";
  */
 declare const ARS_TIME_ZONE: InjectionToken<string>;
 /**
- * Functional interceptor that serialises every `Date` in an outgoing request
- * body as a naive local datetime string (`yyyy-MM-ddTHH:mm:ss`: no `Z`, no offset).
+ * Functional interceptor that closes the date serialisation boundary of the application, in both
+ * directions: it writes the dates of every request and reads back those of every response.
  *
- * WHY: `JSON.stringify` calls `Date.prototype.toJSON`, which emits a UTC instant.
- * A date picked as 29/07/2026 00:00 in Rome (UTC+2) becomes
- * `2026-07-28T22:00:00.000Z`, so the server stores the 28th — the classic
- * "off by one day" bug. Sending the wall-clock value instead makes
- * System.Text.Json produce a `DateTime` with `Kind = Unspecified` and the exact
- * day/time the user selected.
+ * ON THE WAY OUT every `Date` of the request body is serialised as a naive local datetime string
+ * (`yyyy-MM-ddTHH:mm:ss`: no `Z`, no offset). `JSON.stringify` would otherwise call
+ * `Date.prototype.toJSON`, which emits a UTC instant: a date picked as 29/07/2026 00:00 in Rome
+ * (UTC+2) becomes `2026-07-28T22:00:00.000Z`, so the server stores the 28th — the classic
+ * "off by one day". Sending the wall-clock value instead makes System.Text.Json produce a
+ * `DateTime` with `Kind = Unspecified` and the exact day/time the user selected.
  *
- * This is the single serialisation boundary of the application: no call site has
- * to convert anything, and it also covers dates that lost a per-instance
- * `toJSON` along the way (e.g. after `structuredClone`).
+ * ON THE WAY BACK every ISO date string of the response body is read into a `Date`. Models declare
+ * `Date`, but `HttpClient` only runs `JSON.parse`, which has no notion of dates, so without this
+ * every one of those properties holds a `string` at runtime and the declared type is a promise
+ * nobody keeps. It goes unnoticed for a long time — the `date` pipe accepts strings and
+ * {@link DateFnsAdapter.deserialize} parses them for the datepickers — until somebody calls a
+ * method of `Date` on one and gets a `TypeError`, or writes `x.someDate = new Date(x.someDate)` to
+ * work around it one call site at a time.
  *
- * Register it explicitly in `provideHttpClient(withInterceptors([...]))`.
- * If you would rather have the library register it for you, use
- * {@link provideArsLocalDates} instead.
+ * With both halves here no call site has to convert anything, in either direction, and dates that
+ * lost a per-instance `toJSON` along the way (after a `structuredClone`, say) are covered too.
+ *
+ * Both halves are idempotent — a body already normalised holds no `Date`, a body already revived
+ * holds no ISO string — so registering this twice, or over a chain that has already converted,
+ * changes nothing.
+ *
+ * REGISTER IT FIRST in `withInterceptors([...])`. The first interceptor of the array is the first
+ * to see the request and the LAST to see the response, which is what this one wants in both
+ * directions: every other interceptor keeps seeing the body exactly as the server sent it.
+ *
+ * If you would rather have the library register it for you, use {@link provideArsLocalDates}.
  *
  * @example
  * provideHttpClient(withInterceptors([
@@ -254,24 +267,27 @@ declare const arsLocalDateInterceptor: HttpInterceptorFn;
 declare class ArsLocalDateInterceptor implements HttpInterceptor {
     private readonly timeZone;
     /**
-     * Normalises the request body before handing it to the next handler.
+     * Normalises the dates of the request and revives those of the response.
      * @param req  - The outgoing request.
      * @param next - The next handler in the chain.
+     * @returns The stream of events, with the dates of the response body revived.
      */
     intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ArsLocalDateInterceptor, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 /**
- * Standalone providers for date serialisation towards the backend.
+ * Standalone providers for date conversion towards and from the backend.
  *
- * Registers {@link ArsLocalDateInterceptor} so that every `Date` in a request
- * body travels as a naive local datetime string instead of a UTC instant.
+ * Registers {@link ArsLocalDateInterceptor}, so that every `Date` of a request body travels as a
+ * naive local datetime string instead of a UTC instant, and every ISO date string of a response
+ * body comes back as the `Date` the model declares.
  *
  * IMPORTANT: the application MUST call `withInterceptorsFromDi()`, otherwise
  * these providers have no effect at all (no error is raised).
  *
  * @param timeZone - IANA timezone name (default: `Europe/Rome`).
+ * @returns The environment providers to add to the application configuration.
  *
  * @example
  * providers: [
@@ -280,63 +296,6 @@ declare class ArsLocalDateInterceptor implements HttpInterceptor {
  * ]
  */
 declare function provideArsLocalDates(timeZone?: string): EnvironmentProviders;
-/**
- * Functional interceptor that reads every ISO date string in a response body back into a `Date`.
- *
- * WHY: models declare `Date`, but `HttpClient` only runs `JSON.parse`, which has no notion of
- * dates, so without this every one of those properties holds a `string` at runtime and the declared
- * type is a promise nobody keeps. It goes unnoticed for a long time — Angular's `date` pipe accepts
- * strings and {@link DateFnsAdapter.deserialize} parses them for the datepickers — until somebody
- * calls a method of `Date` on one and gets a `TypeError`, or writes
- * `x.someDate = new Date(x.someDate)` to work around it one call site at a time.
- *
- * Together with {@link arsLocalDateInterceptor} it closes the serialisation boundary: no call site
- * has to convert anything, in either direction.
- *
- * NOT registered by {@link provideArsLocalDates}, on purpose: turning strings into Dates changes
- * what an application already reading those fields receives, so it stays opt-in and each
- * application decides when to take it. Register it explicitly, or use
- * {@link provideArsLocalDateResponses}.
- *
- * @example
- * provideHttpClient(withInterceptors([
- *   arsLocalDateInterceptor,
- *   arsLocalDateResponseInterceptor,
- * ]));
- */
-declare const arsLocalDateResponseInterceptor: HttpInterceptorFn;
-/**
- * Class-based twin of {@link arsLocalDateResponseInterceptor}, for the same reason
- * {@link ArsLocalDateInterceptor} exists: only a class can be contributed through
- * `HTTP_INTERCEPTORS` by an `EnvironmentProviders`.
- *
- * REQUIRES `withInterceptorsFromDi()` in the application's `provideHttpClient()`.
- */
-declare class ArsLocalDateResponseInterceptor implements HttpInterceptor {
-    private readonly timeZone;
-    /**
-     * Revives the dates of the response before handing it to the caller.
-     * @param req  - The outgoing request.
-     * @param next - The next handler in the chain.
-     */
-    intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ArsLocalDateResponseInterceptor, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
-}
-/**
- * Standalone providers for date deserialisation coming back from the backend.
- *
- * Registers {@link ArsLocalDateResponseInterceptor}, the counterpart of
- * {@link provideArsLocalDates}. Kept separate because it is the half that changes what existing
- * code receives: an application whose models declare those fields as `string` has to be looked at
- * before switching it on.
- *
- * IMPORTANT: the application MUST call `withInterceptorsFromDi()`, otherwise these providers have
- * no effect at all (no error is raised).
- *
- * @param timeZone - IANA timezone name (default: `Europe/Rome`).
- */
-declare function provideArsLocalDateResponses(timeZone?: string): EnvironmentProviders;
 /**
  * Formats a date as a date-only ISO string (`yyyy-MM-dd`) using its wall-clock
  * calendar day in the given timezone. Use it for query-string parameters and for
@@ -358,4 +317,4 @@ declare function toLocalDateOnlyString(value?: Date | null, timeZone?: string):
  */
 declare function toLocalDateTimeString(value?: Date | null, timeZone?: string): string | undefined;
 
-export { ARS_TIME_ZONE, ArsLocalDateInterceptor, ArsLocalDateResponseInterceptor, DEFAULT_TIME_ZONE, DateFnsAdapter, MAT_DATE_FNS_FORMATS, arsLocalDateInterceptor, arsLocalDateResponseInterceptor, provideArsDateFns, provideArsLocalDateResponses, provideArsLocalDates, toLocalDateOnlyString, toLocalDateTimeString };
+export { ARS_TIME_ZONE, ArsLocalDateInterceptor, DEFAULT_TIME_ZONE, DateFnsAdapter, MAT_DATE_FNS_FORMATS, arsLocalDateInterceptor, provideArsDateFns, provideArsLocalDates, toLocalDateOnlyString, toLocalDateTimeString };

package/types/arsedizioni-ars-utils-ui.navigation.d.ts

@@ -332,6 +332,8 @@ declare class NavigationBarComponent {
     private readonly router;
     private readonly directionality;
     private readonly hostRef;
+    /** Used to schedule the post-render read that reveals a branch just expanded. */
+    private readonly injector;
     private readonly destroyRef;
     /** Flat list of destinations. Ignored when `sections` is provided. */
     readonly items: _angular_core.InputSignal<readonly NavigationItem[]>;
@@ -650,6 +652,24 @@ declare class NavigationBarComponent {
      * @returns `true` when a matching destination was found and focused.
      */
     focusItem(id: string): boolean;
+    /**
+     * Scrolls the list so that the destinations a branch has just revealed are visible.
+     *
+     * Opening a parent sitting near the bottom of the list adds its children BELOW the fold: the
+     * row answers the click, and nothing seems to happen. This scrolls to the end of the branch so
+     * the options show up where the user is already looking.
+     *
+     * The parent row is never pushed out of the top: when a branch is taller than the list, showing
+     * its end would cost the row that was clicked, so the scroll stops with the parent at the top
+     * edge and the branch runs off the bottom — the user reads it downwards from there.
+     *
+     * Only the wide variants expand inline; in the compact ones the children live in the floating
+     * panel and there is nothing to scroll.
+     *
+     * @param id - Identifier of the parent destination that has just been expanded.
+     * @returns void
+     */
+    private revealBranch;
     /**
      * Moves the compact-only destinations of a group into a synthesized overflow
      * destination appended at the end of the group.