@arsedizioni/ars-utils 22.0.83 → 22.0.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arsedizioni/ars-utils",
-  "version": "22.0.83",
+  "version": "22.0.85",
   "author": {
     "email": "software@arsedizioni.it",
     "name": "Fabio Buscaroli, Alberto Doria"

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

@@ -1,11 +1,12 @@
 import * as i0 from '@angular/core';
-import { EnvironmentProviders, PipeTransform, EventEmitter, OnDestroy, Signal } from '@angular/core';
+import { EnvironmentProviders, InjectionToken, PipeTransform, EventEmitter, OnDestroy, Signal } from '@angular/core';
 import { DateAdapter, MatDateFormats } from '@angular/material/core';
 import { Locale } from 'date-fns';
+import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpInterceptorFn } from '@angular/common/http';
+import { Observable } from 'rxjs';
 import { Validator, AbstractControl, ValidationErrors } from '@angular/forms';
 import { SafeHtml, SafeResourceUrl } from '@angular/platform-browser';
 import { SelectionModel } from '@angular/cdk/collections';
-import { Observable } from 'rxjs';
 
 declare const MAT_DATE_FNS_FORMATS: MatDateFormats;
 /**
@@ -206,6 +207,103 @@ declare class DateFnsAdapter extends DateAdapter<Date, Locale> {
  */
 declare function provideArsDateFns(): EnvironmentProviders;
 
+/** Default application timezone: all dates are serialised as Europe/Rome wall-clock values. */
+declare const DEFAULT_TIME_ZONE = "Europe/Rome";
+/**
+ * IANA timezone used to serialise dates towards the backend.
+ * Override it in the application providers to run the same code in another zone:
+ * `{ provide: ARS_TIME_ZONE, useValue: 'Europe/Zurich' }`.
+ */
+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).
+ *
+ * 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.
+ *
+ * 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`).
+ *
+ * Register it explicitly in `provideHttpClient(withInterceptors([...]))`.
+ * If you would rather have the library register it for you, use
+ * {@link provideArsLocalDates} instead.
+ *
+ * @example
+ * provideHttpClient(withInterceptors([
+ *   arsLocalDateInterceptor,
+ *   evolutionAuthInterceptor(...),
+ * ]));
+ */
+declare const arsLocalDateInterceptor: HttpInterceptorFn;
+/**
+ * Class-based twin of {@link arsLocalDateInterceptor}.
+ *
+ * Exists because a functional `HttpInterceptorFn` can ONLY be registered inside
+ * `provideHttpClient(withInterceptors([...]))`, while a class registered on the
+ * `HTTP_INTERCEPTORS` multi-token can be contributed by any `EnvironmentProviders` —
+ * which is what lets {@link provideArsLocalDates} (and `provideArsDateFns`) wire it up
+ * on their own.
+ *
+ * REQUIRES `withInterceptorsFromDi()` in the application's `provideHttpClient()`:
+ * without it Angular never reads `HTTP_INTERCEPTORS` and this interceptor is
+ * silently skipped.
+ */
+declare class ArsLocalDateInterceptor implements HttpInterceptor {
+    private readonly timeZone;
+    /**
+     * Normalises the request body before handing it to the next handler.
+     * @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<ArsLocalDateInterceptor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ArsLocalDateInterceptor>;
+}
+/**
+ * Standalone providers for date serialisation towards 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.
+ *
+ * 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`).
+ *
+ * @example
+ * providers: [
+ *   provideArsLocalDates(),
+ *   provideHttpClient(withInterceptors([evolutionAuthInterceptor(...)]), withInterceptorsFromDi()),
+ * ]
+ */
+declare function provideArsLocalDates(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
+ * DTO fields mapped to a .NET `DateOnly`, which the interceptor cannot detect.
+ *
+ * @param value    - The date to serialise.
+ * @param timeZone - IANA timezone name (default: `Europe/Rome`).
+ * @returns The `yyyy-MM-dd` string, or `undefined` for empty/invalid input.
+ */
+declare function toLocalDateOnlyString(value?: Date | null, timeZone?: string): string | undefined;
+/**
+ * Formats a date as a naive local datetime string (`yyyy-MM-ddTHH:mm:ss`), the
+ * same representation produced by the interceptor. Useful for query-string
+ * parameters, which never pass through the request body.
+ *
+ * @param value    - The date to serialise.
+ * @param timeZone - IANA timezone name (default: `Europe/Rome`).
+ * @returns The naive datetime string, or `undefined` for empty/invalid input.
+ */
+declare function toLocalDateTimeString(value?: Date | null, timeZone?: string): string | undefined;
+
 /**
  * Directive that moves browser focus to the host element after the first render cycle.
  * Apply `autoFocus` to any focusable element to set focus automatically on initialisation.
@@ -1774,5 +1872,5 @@ declare class ThemeService implements OnDestroy {
     static ɵprov: i0.ɵɵInjectableDeclaration<ThemeService>;
 }
 
-export { AutoFocusDirective, BroadcastChannelManager, BroadcastService, CHANNEL_NAME, CopyClipboardDirective, DateFnsAdapter, DateFormat, DateInterval, DateIntervalChangeDirective, DeleteModel, EmailsValidatorDirective, EnvironmentService, EqualsValidatorDirective, FileInfo, FileSizeValidatorDirective, FormatHtmlPipe, FormatMarkdownPipe, FormatPipe, GroupModel, GuidValidatorDirective, IDModel, ImportModel, MAT_DATE_FNS_FORMATS, MaxTermsValidatorDirective, NotEmptyValidatorDirective, NotEqualValidatorDirective, NotFutureValidatorDirective, PasswordValidatorDirective, QueryModel, RelationModel, RemoveFocusDirective, ReplacePipe, SafeHtmlPipe, SafeUrlPipe, ScreenService, SearchCallbackPipe, SearchFilterPipe, SelectableModel, SplashService, SqlDateValidatorDirective, SystemUtils, ThemeService, TimeValidatorDirective, UpdateRelationsModel, UrlValidatorDirective, UtilsMessages, ValidIfDirective, ValidatorDirective, ValueModel, provideArsDateFns };
+export { ARS_TIME_ZONE, ArsLocalDateInterceptor, AutoFocusDirective, BroadcastChannelManager, BroadcastService, CHANNEL_NAME, CopyClipboardDirective, DEFAULT_TIME_ZONE, DateFnsAdapter, DateFormat, DateInterval, DateIntervalChangeDirective, DeleteModel, EmailsValidatorDirective, EnvironmentService, EqualsValidatorDirective, FileInfo, FileSizeValidatorDirective, FormatHtmlPipe, FormatMarkdownPipe, FormatPipe, GroupModel, GuidValidatorDirective, IDModel, ImportModel, MAT_DATE_FNS_FORMATS, MaxTermsValidatorDirective, NotEmptyValidatorDirective, NotEqualValidatorDirective, NotFutureValidatorDirective, PasswordValidatorDirective, QueryModel, RelationModel, RemoveFocusDirective, ReplacePipe, SafeHtmlPipe, SafeUrlPipe, ScreenService, SearchCallbackPipe, SearchFilterPipe, SelectableModel, SplashService, SqlDateValidatorDirective, SystemUtils, ThemeService, TimeValidatorDirective, UpdateRelationsModel, UrlValidatorDirective, UtilsMessages, ValidIfDirective, ValidatorDirective, ValueModel, arsLocalDateInterceptor, provideArsDateFns, provideArsLocalDates, toLocalDateOnlyString, toLocalDateTimeString };
 export type { AddModel, AddResultModel, ApiResponse, ApiResult, BroadcastChannelMessageBag, BroadcastChannelSubscriberInfo, BroadcastMessageInfo, BroadcastMessageToastData, Checkable, DeleteResultModel, DoneResult, EnableDisableModel, ErrorInfo, File, Folder, FolderTree, INode, KeyOf, LoginResult, NameValueItem, PasswordStrength, QueryResultModel, SearchBag, SearchFilterMetadata, Searchable, SendToModel, ThemeType, UpdateModel, UpdateResultModel, Validated };