@arsedizioni/ars-utils 22.5.1 → 22.5.2

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

@@ -0,0 +1,345 @@
+import { Observable } from 'rxjs';
+import * as _angular_core from '@angular/core';
+
+/**
+ * Content of a shell message.
+ *
+ * Deliberately a subset of `InfoDialogData`: the shell speaks before a route exists, so it
+ * says one thing and offers one way out. Anything richer belongs to `DialogService`.
+ */
+interface ShellMessageData {
+    /** Heading shown above the message. */
+    title?: string;
+    /** HTML body of the message. */
+    message: string;
+    /** Optional technical detail (a log, a stack trace) shown in a secondary panel. */
+    details?: string;
+    /** Label of the dismiss button. */
+    okCaption?: string;
+    /** Auto-dismiss delay in milliseconds; the message stays until dismissed when omitted. */
+    dismissAfter?: number;
+    /** Maximum width of the panel in pixels. */
+    width?: number;
+}
+/**
+ * Handle over an open shell message.
+ *
+ * Not a `MatDialogRef`: there is no Material here, and the shell never needs to reach into
+ * the component instance. Closing it and knowing when it closed is the whole contract.
+ */
+interface ShellMessageRef {
+    /**
+     * Closes the message. Does nothing when it has already been closed.
+     * @returns void
+     */
+    close(): void;
+    /** Resolves once the message has been removed from the DOM. */
+    readonly closed: Promise<void>;
+}
+
+/** Visual style of the busy indicator. */
+type ShellBusyType = 'bar' | 'spinner' | 'wait' | 'hourglass';
+/** Progress mode of the bar and of the spinner. */
+type ShellBusyMode = 'determinate' | 'indeterminate';
+/**
+ * Overlay that blocks interaction while an operation is running, in the four styles the
+ * applications use: progress bar, spinner, hourglass and bare wait.
+ *
+ * Reproduces `mat-progress-bar` and `mat-progress-spinner` in CSS and SVG rather than importing
+ * them, because this overlay is shown from the boot path — an HTTP interceptor calls it before
+ * any route exists — and `ui.shell` exists precisely so that path costs no Material.
+ *
+ * The instance is created once by {@link ShellService} and then reused: showing and hiding is a
+ * class on the host, never a `createComponent`, so the 40-odd calls a screen costs nothing.
+ */
+declare class ShellBusyComponent {
+    /** Whether the overlay is on screen. Hidden with `display: none`, so it costs no layout. */
+    readonly visible: _angular_core.WritableSignal<boolean>;
+    /** Visual style of the indicator. */
+    readonly type: _angular_core.WritableSignal<ShellBusyType>;
+    /** Current progress value (0-100), used when {@link progressMode} is `'determinate'`. */
+    readonly progress: _angular_core.WritableSignal<number>;
+    /** Progress mode of the bar and of the spinner. */
+    readonly progressMode: _angular_core.WritableSignal<ShellBusyMode>;
+    /** Message displayed above the indicator. */
+    readonly message: _angular_core.WritableSignal<string>;
+    /** Circumference of the spinner circle, bound to `stroke-dasharray`. */
+    protected readonly circumference: number;
+    /** Length of the spinner arc still to be drawn, derived from {@link progress}. */
+    protected readonly dashOffset: _angular_core.Signal<number>;
+    /**
+     * Updates the overlay state.
+     *
+     * Same contract as the `BusyDialogComponent` it replaces, down to the two implicit rules that
+     * callers rely on: an empty message keeps the previous text (so `wait()` does not wipe it), and
+     * a progress above zero forces `'determinate'` whatever the caller passed.
+     * @param message      - New message to display. An empty string preserves the current one.
+     * @param progress     - Current progress value (0-100). Above zero it forces determinate mode.
+     * @param progressMode - Progress mode to use. Defaults to `'indeterminate'`.
+     * @param type         - Visual style to use. Defaults to `'bar'`.
+     * @returns void
+     */
+    set(message: string, progress: number, progressMode?: ShellBusyMode, type?: ShellBusyType): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellBusyComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellBusyComponent, "ars-shell-busy", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Everything the application can say to the user without asking anything back: a message, an
+ * error, and the wait overlay. No Angular Material behind any of it.
+ *
+ * `DialogService` extends this class, so a route component injects `DialogService` and has both
+ * halves; shell, HTTP interceptors, route guards and app initializers inject `ShellService` and
+ * pay for neither `mat-dialog` nor `cdk/overlay` on the boot path — measured at 445 KB of the
+ * 905 KB initial bundle on myARS, more than every route of the application put together.
+ *
+ * The methods keep the parameter order of the `DialogService` ones they came from, so no call
+ * site changed when they moved here.
+ *
+ * ## Stacking
+ *
+ * Outside the CDK overlay stack the order is a fixed z-index: the busy overlay sits at 1090 and
+ * the message at 1100, both above the `cdk-overlay-container` (1000). So an error raised while a
+ * Material dialog is open lands on top of it, which is what an error should do, and the busy
+ * overlay covers the dialog it belongs to. The one case a fixed number cannot express is a dialog
+ * opened while the overlay is still up — `DialogService.open()` takes the busy away immediately
+ * rather than with the grace period, precisely so that case cannot happen.
+ */
+declare class ShellService {
+    private readonly appRef;
+    private readonly environmentInjector;
+    private messageRef?;
+    private messageKind?;
+    private resolveClosed?;
+    private previousOverflow?;
+    private previouslyFocused?;
+    private busyRef?;
+    private busyVisible;
+    private busyActionSubscription?;
+    private clearBusyTimer?;
+    /**
+     * Shows an informational message.
+     * @param message      - HTML message to display.
+     * @param title        - Heading. Defaults to `'Informazioni'`.
+     * @param okCaption    - Dismiss button label. Defaults to `'Ok'`.
+     * @param width        - Maximum panel width in pixels. Defaults to `500`.
+     * @param dismissAfter - Auto-close delay in milliseconds (optional).
+     * @param details      - Optional secondary details text.
+     * @returns A handle over the open message, or `null` outside the browser.
+     */
+    info(message: string, title?: string, okCaption?: string, width?: number, dismissAfter?: number, details?: string): ShellMessageRef | null;
+    /**
+     * Shows an error message. When one is already on screen its content is replaced in place: a
+     * failing API answers many requests at once, and each of them must not add a panel of its own.
+     * @param message      - HTML error message to display.
+     * @param log          - Optional technical log or stack trace shown in the details panel.
+     * @param title        - Heading. Defaults to `'Errore'`.
+     * @param okCaption    - Dismiss button label. Defaults to `'Ok'`.
+     * @param width        - Maximum panel width in pixels. Defaults to `500`.
+     * @param dismissAfter - Auto-close delay in milliseconds (optional).
+     * @returns A handle over the open message, or `null` outside the browser.
+     */
+    error(message: string, log?: string, title?: string, okCaption?: string, width?: number, dismissAfter?: number): ShellMessageRef | null;
+    /**
+     * Closes the message currently on screen, if any. Does not touch the busy overlay.
+     * @returns void
+     */
+    closeMessage(): void;
+    /**
+     * Opens the message panel, or updates the one already open when it is showing the same kind of
+     * message.
+     * @param kind - Whether this is an informational or an error message.
+     * @param data - The content to display.
+     * @returns A handle over the open message, or `null` outside the browser.
+     */
+    private showMessage;
+    /**
+     * Builds the handle returned to callers, wiring its `closed` promise to the current message.
+     * @returns The handle over the message currently on screen.
+     */
+    private messageHandle;
+    /**
+     * Shows or updates the busy overlay.
+     *
+     * Called dozens of times per screen, so it creates nothing after the first time: the component
+     * is built once and then kept, and showing it again is a class on the host element. The state
+     * is written to signals and checked synchronously before returning, so the message on screen is
+     * always the last one asked for — a second `busy()` in the same task never leaves the previous
+     * text behind.
+     * @param message      - Text to display. An empty string keeps the current one.
+     * @param progress     - Progress value (`-1` = indeterminate). Defaults to `-1`.
+     * @param progressMode - Progress mode. Defaults to `'indeterminate'`.
+     * @param type         - Visual style of the overlay. Defaults to `'bar'`.
+     * @param action       - Optional observable; the overlay is dismissed when it first emits. It
+     *                       replaces the one passed to a previous call, which is unsubscribed.
+     * @returns `true` if the overlay was brought up by this call, `false` if it was already up.
+     */
+    setBusy(message: string, progress?: number, progressMode?: ShellBusyMode, type?: ShellBusyType, action?: Observable<unknown>): boolean;
+    /**
+     * Shows or updates the busy overlay using the progress-bar style.
+     * @param message      - Text to display inside the overlay.
+     * @param progress     - Progress value (`-1` = indeterminate). Defaults to `-1`.
+     * @param progressMode - Progress mode. Defaults to `'indeterminate'`.
+     * @param action       - Optional observable; the overlay is dismissed when it emits.
+     * @returns `true` if the overlay was brought up by this call.
+     */
+    busy(message: string, progress?: number, progressMode?: ShellBusyMode, action?: Observable<unknown>): boolean;
+    /**
+     * Shows or updates the busy overlay using the spinner style.
+     * @param message      - Text to display inside the overlay.
+     * @param progress     - Progress value (`-1` = indeterminate). Defaults to `-1`.
+     * @param progressMode - Progress mode. Defaults to `'indeterminate'`.
+     * @param action       - Optional observable; the overlay is dismissed when it emits.
+     * @returns `true` if the overlay was brought up by this call.
+     */
+    busySpinner(message: string, progress?: number, progressMode?: ShellBusyMode, action?: Observable<unknown>): boolean;
+    /**
+     * Shows or updates the busy overlay using the hourglass style.
+     * @param message - Text to display inside the overlay.
+     * @param action  - Optional observable; the overlay is dismissed when it emits.
+     * @returns `true` if the overlay was brought up by this call.
+     */
+    busyHourglass(message: string, action?: Observable<unknown>): boolean;
+    /**
+     * Shows a bare wait indicator, with no panel and no message.
+     * @param action - Optional observable; the overlay is dismissed when it emits.
+     * @returns `true` if the overlay was brought up by this call.
+     */
+    wait(action?: Observable<unknown>): boolean;
+    /**
+     * Returns a {@link BusyTimer} that brings the overlay up only if the operation is still running
+     * after a debounce delay.
+     * @param message - Text to display. Defaults to `'Operazione in corso...'`.
+     * @param due     - Delay in milliseconds before the overlay appears. Defaults to `100`.
+     * @returns A timer that must be disposed with `clear()` when the operation ends.
+     */
+    busyTimer(message?: string, due?: number): BusyTimer;
+    /**
+     * Takes the busy overlay away.
+     *
+     * By default it waits a short grace period, so that a chain of quick operations does not make
+     * the overlay blink between one and the next; any `setBusy()` in the meantime cancels the
+     * pending removal. Pass `true` when something is about to be drawn underneath it and the wait
+     * would be visible — that is what `DialogService.open()` does.
+     * @param immediate - When `true`, removes the overlay without waiting for the grace period.
+     * @returns void
+     */
+    clearBusy(immediate?: boolean): void;
+    /**
+     * Hides the busy overlay without destroying it, so the next call can reuse the instance.
+     * @returns void
+     */
+    private hideBusy;
+    /**
+     * Returns the busy component, creating and attaching it the first time it is needed.
+     * @returns The reused busy component reference.
+     */
+    private ensureBusy;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ShellService>;
+}
+
+/**
+ * Shows the busy overlay only if the operation is still running after a debounce delay, so that
+ * an operation that answers in 30 ms never makes the screen flash.
+ *
+ * Whoever creates one owns it: {@link clear} must be called when the operation ends, otherwise
+ * the overlay appears after the fact and stays.
+ */
+declare class BusyTimer {
+    private readonly shellService;
+    private readonly subscription;
+    /**
+     * Arms the timer.
+     * @param shellService - The service that owns the overlay. A `DialogService` is accepted too,
+     *                       since it extends `ShellService`.
+     * @param due          - Delay in milliseconds before the overlay appears. Defaults to `100`.
+     * @param message      - Text to display. Defaults to `'Operazione in corso...'`.
+     */
+    constructor(shellService: ShellService, due?: number, message?: string);
+    /**
+     * Disarms the timer and takes the overlay away.
+     * @returns void
+     */
+    clear(): void;
+}
+
+/**
+ * The shell's message panel: a modal that looks like a Material dialog and owes nothing to
+ * Material.
+ *
+ * It exists because shell, interceptors, guards and app initializers must be able to say
+ * "the session is gone" before a single route has been loaded, and paying for `mat-dialog`,
+ * `cdk/overlay` and the rest of that stack on the boot path costs the initial bundle more
+ * than every route of the application put together. The look is matched through CSS custom
+ * properties (`--ars-*` first, Material's `--mat-sys-*` next, a literal last), so an
+ * application that themes Material gets the same surface here for free.
+ *
+ * Instantiated imperatively by {@link ShellService}, never declared in a template: that is
+ * what lets an interceptor open it.
+ */
+declare class ShellMessageComponent {
+    /** Emitted when the user dismisses the message, whichever way they did it. */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    private readonly panel;
+    private readonly okButton;
+    /** Unique id tying the panel to its heading for assistive technology. */
+    protected readonly titleId: string;
+    /** Current content, with the defaults the shell relies on already applied. */
+    protected readonly data: _angular_core.WritableSignal<ShellMessageData>;
+    /** True for a moment after a successful copy, so the button can acknowledge it. */
+    protected readonly copied: _angular_core.WritableSignal<boolean>;
+    private dismissTimer?;
+    private copiedTimer?;
+    private closing;
+    constructor();
+    /**
+     * Replaces the content shown by the panel and restarts the auto-dismiss timer.
+     *
+     * Called on an already open panel by `ShellService.error()` so that a burst of failures
+     * updates one message instead of stacking modals nobody can dismiss.
+     * @param data - The new content to display.
+     * @returns void
+     */
+    setData(data: ShellMessageData): void;
+    /**
+     * Dismisses the panel. Safe to call more than once: only the first call is announced.
+     * @returns void
+     */
+    close(): void;
+    /**
+     * Closes the panel on Escape, mirroring a Material dialog opened with the default config.
+     * @param e - The keyboard event captured at document level.
+     * @returns void
+     */
+    protected onKeydown(e: KeyboardEvent): void;
+    /**
+     * Keeps Tab inside the panel while the message is up.
+     *
+     * A hand-rolled two-element version of what `cdk/a11y` does, which is all this panel needs:
+     * it never holds more than the copy button and the dismiss button.
+     * @param e - The Tab keydown event.
+     * @returns void
+     */
+    private trapFocus;
+    /**
+     * (Re)schedules the auto-dismiss timer, cancelling any pending one so a timer armed for an
+     * earlier message can never close a newer one.
+     * @param dismissAfter - Delay in milliseconds; no-op when falsy.
+     * @returns void
+     */
+    private scheduleDismiss;
+    /**
+     * Copies the message and its details to the clipboard, as both HTML and plain text.
+     *
+     * Unlike `InfoDialogComponent` there is no toast to report the outcome — the shell has no
+     * toast — so the button itself acknowledges it for a moment.
+     * @returns A promise that resolves once the copy has been attempted.
+     */
+    protected copy(): Promise<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellMessageComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellMessageComponent, "ars-shell-message", never, {}, { "closed": "closed"; }, never, never, true, never>;
+}
+
+export { BusyTimer, ShellBusyComponent, ShellMessageComponent, ShellService };
+export type { ShellBusyMode, ShellBusyType, ShellMessageData, ShellMessageRef };