@arsedizioni/ars-utils 22.1.5 → 22.5.2

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

@@ -0,0 +1,304 @@
+import * as i0 from '@angular/core';
+import { EnvironmentProviders, InjectionToken } 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';
+
+declare const MAT_DATE_FNS_FORMATS: MatDateFormats;
+/**
+ * date-fns adapter that integrates Angular Material's date picker with the date-fns library,
+ * applying `Europe/Rome` timezone for all parsed and created dates.
+ */
+declare class DateFnsAdapter extends DateAdapter<Date, Locale> {
+    constructor();
+    /**
+     * Wraps a date/instant into a Europe/Rome TZDate whose JSON serialisation emits a
+     * naive local datetime string ("yyyy-MM-dd'T'HH:mm:ss") instead of a UTC instant,
+     * so the wall-clock value the user entered is preserved end-to-end (no timezone shift).
+     * @param value - The source Date or Unix timestamp in milliseconds.
+     * @returns a Europe/Rome TZDate whose toJSON yields a naive local datetime string.
+     */
+    private static toLocal;
+    /**
+     * Returns the year component of the given date.
+     * @param date - The source date.
+     */
+    getYear(date: Date): number;
+    /**
+     * Returns the zero-based month index of the given date (0 = January).
+     * @param date - The source date.
+     */
+    getMonth(date: Date): number;
+    /**
+     * Returns the day-of-month of the given date (1-based).
+     * @param date - The source date.
+     */
+    getDate(date: Date): number;
+    /**
+     * Returns the day-of-week of the given date (0 = Sunday).
+     * @param date - The source date.
+     */
+    getDayOfWeek(date: Date): number;
+    /**
+     * Returns an array of 12 month name strings formatted for the active locale.
+     * @param style - One of `'long'`, `'short'`, or `'narrow'`.
+     */
+    getMonthNames(style: 'long' | 'short' | 'narrow'): string[];
+    /**
+     * Returns an array of 31 day-of-month label strings formatted using `Intl.DateTimeFormat`
+     * when available, falling back to plain numeric strings.
+     */
+    getDateNames(): string[];
+    /**
+     * Returns an array of 7 day-of-week name strings formatted for the active locale.
+     * @param style - One of `'long'`, `'short'`, or `'narrow'`.
+     */
+    getDayOfWeekNames(style: 'long' | 'short' | 'narrow'): string[];
+    /**
+     * Returns the four-digit year string for the given date.
+     * @param date - The source date.
+     */
+    getYearName(date: Date): string;
+    /**
+     * Returns the first day of the week for the active locale (0 = Sunday, 1 = Monday, …).
+     */
+    getFirstDayOfWeek(): number;
+    /**
+     * Returns the number of days in the month of the given date.
+     * @param date - The source date.
+     */
+    getNumDaysInMonth(date: Date): number;
+    /**
+     * Creates an independent copy of the given date.
+     * @param date - The date to clone.
+     */
+    clone(date: Date): Date;
+    /**
+     * Creates a `Date` in the `Europe/Rome` timezone for the given year, month, and day.
+     * Throws an `Error` when any component is out of range.
+     * @param year  - Full four-digit year.
+     * @param month - Zero-based month index (0 = January, 11 = December).
+     * @param date  - Day-of-month (1-based).
+     */
+    createDate(year: number, month: number, date: number): Date;
+    /**
+     * Returns the current date and time in the Europe/Rome timezone, preserving the wall-clock value.
+     */
+    today(): Date;
+    /**
+     * Parses a value into a `Date`.
+     * - Strings are first attempted as ISO 8601, then matched against each format in `parseFormat`.
+     * - Numbers are treated as Unix timestamps (milliseconds).
+     * - Existing `Date` instances are cloned.
+     * @param value       - The value to parse.
+     * @param parseFormat - A format string or an array of format strings (date-fns tokens).
+     * @returns A valid `Date` in `Europe/Rome`, an invalid sentinel, or `null` for unrecognised input.
+     */
+    parse(value: unknown, parseFormat: string | string[]): Date | null;
+    /**
+     * Formats a `Date` using the given date-fns display format string.
+     * Throws an `Error` when `date` is not valid.
+     * @param date          - The date to format.
+     * @param displayFormat - A date-fns format string (e.g. `'P'`, `'LLL uuuu'`).
+     */
+    format(date: Date, displayFormat: string): string;
+    /**
+     * Adds the given number of whole years to a date.
+     * @param date  - The base date.
+     * @param years - Number of years to add (can be negative).
+     */
+    addCalendarYears(date: Date, years: number): Date;
+    /**
+     * Adds the given number of whole months to a date.
+     * @param date   - The base date.
+     * @param months - Number of months to add (can be negative).
+     */
+    addCalendarMonths(date: Date, months: number): Date;
+    /**
+     * Adds the given number of whole days to a date.
+     * @param date - The base date.
+     * @param days - Number of days to add (can be negative).
+     */
+    addCalendarDays(date: Date, days: number): Date;
+    /**
+     * Serialises a date to an ISO 8601 date-only string (`yyyy-MM-dd`) using its Europe/Rome calendar day,
+     * independent of the browser timezone.
+     * @param date - The date to serialise.
+     * @returns the yyyy-MM-dd string for the date in Europe/Rome.
+     */
+    toIso8601(date: Date): string;
+    /**
+     * Returns the given value when it is a valid `Date`, or `null` for an empty string.
+     * Deserialises valid ISO 8601 strings into `Date` instances.
+     * Delegates all other values to the base-class implementation.
+     * @param value - The raw value to deserialise.
+     */
+    deserialize(value: unknown): Date | null;
+    /**
+     * Returns `true` when `obj` is an instance of `Date`.
+     * @param obj - The object to test.
+     */
+    isDateInstance(obj: unknown): boolean;
+    /**
+     * Returns `true` when `date` represents a valid point in time.
+     * @param date - The date to validate.
+     */
+    isValid(date: Date): boolean;
+    /**
+     * Returns a sentinel `Date` that represents an invalid date (`new Date(NaN)`).
+     */
+    invalid(): Date;
+    /**
+     * Returns the hours component (0-23) of the given date.
+     * @param date - The source date.
+     */
+    getHours(date: Date): number;
+    /**
+     * Returns the minutes component (0-59) of the given date.
+     * @param date - The source date.
+     */
+    getMinutes(date: Date): number;
+    /**
+     * Returns the seconds component (0-59) of the given date.
+     * @param date - The source date.
+     */
+    getSeconds(date: Date): number;
+    /**
+     * Returns a clone of `target` with its time-of-day set to the given hours/minutes/seconds,
+     * keeping the date part unchanged.
+     * @param target  - The date whose time should be set.
+     * @param hours   - New hours (0-23).
+     * @param minutes - New minutes (0-59).
+     * @param seconds - New seconds (0-59).
+     */
+    setTime(target: Date, hours: number, minutes: number, seconds: number): Date;
+    /**
+     * Adds the given number of seconds to a date.
+     * @param date   - The base date.
+     * @param amount - Number of seconds to add (can be negative).
+     */
+    addSeconds(date: Date, amount: number): Date;
+    /**
+     * Parses a time-only value into a `Date` (today's date, in `Europe/Rome`, with the parsed
+     * time-of-day set). The wall-clock time is preserved exactly as entered.
+     * @param value       - The value to parse (a string, or an existing `Date`).
+     * @param parseFormat - A format string or an array of format strings (date-fns tokens).
+     * @returns the parsed Date, an invalid sentinel, or null for unrecognised input.
+     */
+    parseTime(value: unknown, parseFormat: string | string[]): Date | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DateFnsAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DateFnsAdapter>;
+}
+/**
+ * Standalone providers for the ARS date-fns adapter.
+ *
+ * Configures Angular Material to use {@link DateFnsAdapter} (Europe/Rome timezone)
+ * and the matching {@link MAT_DATE_FNS_FORMATS}. Also supports `mat-timepicker` since
+ * {@link DateFnsAdapter} implements the time-related `DateAdapter` methods.
+ *
+ * @example
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideArsDateFns()]
+ * });
+ */
+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;
+
+export { ARS_TIME_ZONE, ArsLocalDateInterceptor, DEFAULT_TIME_ZONE, DateFnsAdapter, MAT_DATE_FNS_FORMATS, arsLocalDateInterceptor, provideArsDateFns, provideArsLocalDates, toLocalDateOnlyString, toLocalDateTimeString };

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

@@ -0,0 +1,159 @@
+import * as i0 from '@angular/core';
+import { PipeTransform } from '@angular/core';
+import { SafeHtml } from '@angular/platform-browser';
+
+/**
+ * Zero-dependency Markdown to HTML converter.
+ *
+ * Design goals:
+ * - Single line-based pass over blocks (no repeated full-string regex passes).
+ * - Inline formatting never touches code spans / code blocks (stash & restore).
+ * - No HTML entity escaping by default in normal text: the source passes as-is.
+ *   Exception: the content of code spans / code blocks is ALWAYS escaped, so
+ *   things like List<string> render correctly (the browser displays the
+ *   original characters; entities never reach the user or the clipboard).
+ *   Opt-in full escaping via { escapeHtml: true } for untrusted input.
+ * - URL sanitization on links/images (javascript:, vbscript:, data: are dropped).
+ * - Bounded result cache for repeated renders (Angular change detection friendly).
+ *
+ * Supported syntax: headings, paragraphs, hard/soft breaks, hr, blockquotes
+ * (nested), fenced code blocks, inline code, bold/italic/strikethrough, links
+ * (with title), images, autolinked bare URLs, ordered/unordered lists (nested,
+ * task lists, ordered start offset), GFM tables with alignment, raw HTML
+ * blocks (e.g. <table>...</table>) passed through verbatim when escapeHtml
+ * is false: their newlines stay plain newlines, never converted to <br>.
+ *
+ * Known simplifications (documented, by design):
+ * - A blank line terminates a list.
+ * - Setext headings (=== / ---) are not supported, use # syntax.
+ * - Reference-style links [text][ref] are not supported.
+ */
+interface MarkdownOptions {
+    /**
+     * Escape raw HTML found in the source as entities (default: false).
+     * When false (default) no &amp;/&lt;/&gt;/&quot; entities are ever produced:
+     * the text is emitted as-is. Enable ONLY when rendering untrusted input,
+     * since raw HTML in the source would otherwise reach the DOM (XSS).
+     */
+    escapeHtml?: boolean;
+    /** Render single newlines inside paragraphs as <br> (default: true). */
+    breaks?: boolean;
+}
+declare class MarkdownUtils {
+    private static readonly cache;
+    private static readonly CACHE_MAX;
+    /** Clears the internal result cache. */
+    static clearCache(): void;
+    /**
+     * Convert markdown to HTML.
+     * @param markdown : the markdown source
+     * @param options  : conversion options
+     * @returns        : the HTML string ('' when input is falsy)
+     */
+    static toHtml(markdown?: string, options?: MarkdownOptions): string;
+    /** Block-level HTML tags that start a raw HTML block (passthrough, no <p>/<br>). */
+    private static readonly htmlBlockTags;
+    /** Void/self-contained tags: a single tag, no closing tag expected. */
+    private static readonly htmlVoidTags;
+    /**
+     * Precompiled: first block-level tag occurrence anywhere in a line.
+     * Anchored on the '<' literal, so scanning is cheap; the lookahead
+     * prevents partial matches ('<td' must not match inside '<tdx').
+     */
+    private static readonly htmlBlockScanRe;
+    /** Result of scanning a line for the start of a raw HTML block. */
+    private static findHtmlBlockStart;
+    /** True when `index` falls inside an inline code span (odd backtick count before it). */
+    private static insideCodeSpan;
+    /**
+     * indexOf-based depth scanner (no regex, no allocations): walks `text`
+     * adjusting `depth` for <tag ...> / </tag> occurrences of the SAME tag.
+     * Self-closing <tag ... /> forms do not alter depth.
+     * @returns [newDepth, endIndex] where endIndex is the position right after
+     *          the '>' that balanced the element, or -1 when still open.
+     */
+    private static scanHtmlDepth;
+    /** A tag token must be followed by whitespace, '/', '>' or end of line. */
+    private static isTagBoundary;
+    /**
+     * Re-injects the remainder of a partially consumed line so the main loop
+     * processes it as markdown. Returns the index the loop should resume from.
+     */
+    private static pushBack;
+    /**
+     * Emits a raw HTML block starting at `hit.index` of lines[i], consuming
+     * following lines until the element is balanced. Text after the block on
+     * the closing line is pushed back for markdown processing.
+     * @returns the index of the last consumed line
+     */
+    private static emitHtmlBlock;
+    private static parseBlocks;
+    /** Matches "- item", "* item", "+ item", "1. item", "1) item" with leading indent. */
+    private static readonly listItemRe;
+    /**
+     * Gathers the contiguous list block starting at `start`, builds it (with
+     * nesting) and returns [html, indexOfLastConsumedLine].
+     */
+    private static parseList;
+    private static buildList;
+    private static tableAligns;
+    private static tableRow;
+    /**
+     * Applies inline markdown to a single text segment.
+     * Generated HTML (code, links, images, autolinks) is stashed behind \u0000
+     * placeholders so later regex passes can never corrupt it.
+     */
+    private static inline;
+    /** Escapes quotes for safe interpolation inside a double-quoted HTML attribute. */
+    private static escapeAttr;
+    /** Escapes &, <, > and " for safe HTML interpolation. */
+    private static escape;
+    /**
+     * Returns a sanitized URL or undefined when the scheme is dangerous.
+     * Blocks javascript:, vbscript: and data: (also when obfuscated with
+     * whitespace/control characters, e.g. "java\tscript:").
+     */
+    private static safeUrl;
+    /**
+     * Copies markdown content to the clipboard in two flavors:
+     * - text/html  : the rendered HTML (rich paste into Word, Outlook, Gmail...)
+     * - text/plain : the original markdown source (paste into editors, IDEs...)
+     * @param markdown : the markdown source
+     * @param options  : conversion options for the HTML flavor
+     * @returns        : true on success
+     */
+    static copyToClipboard(markdown?: string, options?: MarkdownOptions): Promise<boolean>;
+    /**
+     * Copies plain text (e.g. the content of a single code block) to the clipboard.
+     * @param text : the text to copy
+     * @returns    : true on success
+     */
+    static copyText(text?: string): Promise<boolean>;
+    /**
+     * Extracts the visible plain text from a rendered element
+     * (what the user sees, entities already decoded by the browser).
+     * @param element : the element hosting the rendered markdown
+     * @returns       : the plain text
+     */
+    static elementToText(element: HTMLElement): string;
+}
+
+/**
+ * Pipe that converts a Markdown string to sanitized HTML using `MarkdownUtils.toHtml`.
+ *
+ * Usage: `{{ text | formatMarkdown }}`
+ */
+declare class FormatMarkdownPipe implements PipeTransform {
+    private readonly sanitizer;
+    /**
+     * Transforms a Markdown string into sanitized HTML.
+     * @param value - The Markdown input to convert. Treated as an empty string when `undefined`.
+     * @returns A `SafeHtml` value that can be rendered with `[innerHTML]`.
+     */
+    transform(value?: string): SafeHtml;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormatMarkdownPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<FormatMarkdownPipe, "formatMarkdown", true>;
+}
+
+export { FormatMarkdownPipe, MarkdownUtils };
+export type { MarkdownOptions };