@arsedizioni/ars-utils 22.1.5 → 22.5.2

package/types/arsedizioni-ars-utils-ui.dialogs.auth.d.ts

@@ -0,0 +1,224 @@
+import * as _angular_core from '@angular/core';
+import { ElementRef } from '@angular/core';
+import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors, NgForm } from '@angular/forms';
+import { PasswordStrength } from '@arsedizioni/ars-utils/core';
+import { CredentialsDialogResult, ResetPasswordDialogResult, RecoverPasswordDialogResult, PromptOtpDialogResult, PromptDialogData } from '@arsedizioni/ars-utils/ui';
+import { MatFormFieldAppearance } from '@angular/material/form-field';
+
+declare class OtpInputComponent implements ControlValueAccessor, Validator {
+    /** Signal-based query for all individual OTP digit input elements. */
+    readonly otpFields: _angular_core.Signal<readonly ElementRef<HTMLInputElement>[]>;
+    /** `true` when every digit slot contains a valid single decimal digit. */
+    readonly isValid: _angular_core.Signal<boolean>;
+    /** Array of per-digit values backing the OTP display. */
+    readonly otpArray: _angular_core.WritableSignal<string[]>;
+    /** Whether the control is currently disabled. */
+    readonly disabled: _angular_core.WritableSignal<boolean>;
+    private onChange;
+    private onTouched;
+    /**
+     * Writes a new value into the control from the model.
+     * @param value - A string of up to 6 digits to pre-fill the OTP fields.
+     */
+    writeValue(value: string): void;
+    /**
+     * Registers the callback invoked when the control value changes.
+     * @param fn - The callback function.
+     */
+    registerOnChange(fn: (val: string) => void): void;
+    /**
+     * Registers the callback invoked when the control is touched.
+     * @param fn - The callback function.
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Enables or disables the control.
+     * @param isDisabled - `true` to disable all OTP inputs.
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * Validates the OTP value: an empty code is left to `required`, while a
+     * PARTIAL code (e.g. "12") is reported as invalid. Without this, the joined
+     * value "12" was a non-empty string and `required` let the form submit
+     * with an incomplete OTP.
+     * @param control - The form control bound to this component.
+     * @returns `null` when empty or complete (6 digits), `{ otp: true }` otherwise.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    /**
+     * Marks the control as touched when an OTP field loses focus.
+     */
+    onBlur(): void;
+    /**
+     * Blocks non-digit characters before they are inserted.
+     * @param event - The `beforeinput` event from the input element.
+     */
+    onBeforeInput(event: InputEvent): void;
+    /**
+       * Handles digit input, sanitizes it, syncs the DOM, updates the OTP array, and advances focus.
+       * @param event - The `input` event from the digit field.
+       * @param index - Zero-based index of the field that received input.
+       */
+    onInput(event: Event, index: number): void;
+    /**
+     * Handles the Backspace key by moving focus to the previous field when the current one is empty.
+     * @param event - The `keydown` event.
+     * @param index - Zero-based index of the field that received the keydown.
+     */
+    onKeyDown(event: KeyboardEvent, index: number): void;
+    /**
+     * Handles paste events by extracting up to 6 digits and distributing them across the OTP fields.
+     * @param event - The `ClipboardEvent` from the paste action.
+     */
+    onPaste(event: ClipboardEvent): void;
+    /**
+     * Clears every digit field, propagates the empty value to the form model and
+     * moves focus back to the first field. Does not mark the control as touched,
+     * so no validation error is shown right after the reset.
+     */
+    clear(): void;
+    /**
+     * Moves focus to the OTP field at the given index.
+     * @param index - Zero-based index of the target field.
+     */
+    private focusField;
+    /**
+     * Notifies the form model of the current OTP value and marks the control as touched.
+     */
+    private updateModel;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OtpInputComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OtpInputComponent, "otp-input", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Displays a password-strength indicator for the provided password string.
+ * Uses `SystemUtils.calculatePasswordStrength` to derive the score and label.
+ */
+declare class PasswordStrengthComponent {
+    /** The password to evaluate. An empty string renders the default (score 0) state. */
+    readonly password: _angular_core.InputSignal<string>;
+    /**
+     * Computed strength result for the current password.
+     * Falls back to `DEFAULT_STRENGTH` when the password is empty.
+     */
+    protected readonly strength: _angular_core.Signal<PasswordStrength>;
+    /**
+     * CSS class applied to the label element based on the numeric score (1–6 bands).
+     * Scores ≤ 2 → `'score-2'`, ≤ 3 → `'score-3'`, etc.
+     */
+    protected readonly scoreClass: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PasswordStrengthComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PasswordStrengthComponent, "password-strength", never, { "password": { "alias": "password"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface CredentialsDialogData {
+    title?: string;
+    message?: string;
+    remember?: boolean;
+    recoverPassword?: boolean;
+    recoverPasswordUrl?: string;
+    user?: string;
+    okCaption?: string;
+    mode?: 'email' | 'user' | 'otp';
+    appearance?: MatFormFieldAppearance;
+}
+declare class CredentialsDialogComponent {
+    /** Emitted when the user submits the form. Carries the entered credentials. */
+    readonly done: _angular_core.OutputEmitterRef<CredentialsDialogResult>;
+    /** Emitted when the user requests a password-recovery flow. */
+    readonly recoveringPassword: _angular_core.OutputEmitterRef<CredentialsDialogResult>;
+    /** Dialog configuration with defaults applied at construction time. */
+    protected readonly dialogData: _angular_core.WritableSignal<CredentialsDialogData>;
+    /** Current form model, pre-filled with the user name from dialog data when provided. */
+    protected item: CredentialsDialogResult;
+    /** Whether the password field is currently shown as plain text. */
+    protected readonly showPassword: _angular_core.WritableSignal<boolean>;
+    /**
+     * Switches the input mode of the dialog at runtime (e.g. from login to OTP).
+     * Intended to be called from outside via the dialog component reference.
+     * @param mode    - The new input mode (`'email'`, `'user'`, or `'otp'`).
+     * @param message - Optional new message to display above the form.
+     */
+    changeMode(mode: 'email' | 'user' | 'otp', message?: string): void;
+    /**
+     * Emits the current form result and closes the dialog.
+     */
+    protected ok(): void;
+    /**
+     * Emits the current form result for the password-recovery flow and optionally
+     * opens the recovery URL in a new tab.
+     */
+    protected recoverPassword(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CredentialsDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CredentialsDialogComponent, "ng-component", never, {}, { "done": "done"; "recoveringPassword": "recoveringPassword"; }, never, never, true, never>;
+}
+
+type ResetPasswordDialogMode = 'admin' | 'old' | 'otp' | 'forgot';
+interface ResetPasswordDialogData {
+    mode: ResetPasswordDialogMode;
+    userId?: number;
+    userEmail?: string;
+    appearance?: MatFormFieldAppearance;
+}
+declare class ResetPasswordDialogComponent {
+    /** Emitted when the user submits the new password. Carries the entered password data. */
+    readonly done: _angular_core.OutputEmitterRef<ResetPasswordDialogResult>;
+    private readonly dialogService;
+    private readonly dialogRef;
+    /** Dialog configuration with defaults applied at construction time. */
+    protected readonly dialogData: _angular_core.WritableSignal<ResetPasswordDialogData>;
+    /** Current form model bound to the template inputs. */
+    protected item: ResetPasswordDialogResult;
+    /** Whether the old-password field is currently shown as plain text. */
+    protected readonly showOldPassword: _angular_core.WritableSignal<boolean>;
+    /** Whether the new-password field is currently shown as plain text. */
+    protected readonly showPassword: _angular_core.WritableSignal<boolean>;
+    /** Whether the confirm-password field is currently shown as plain text. */
+    protected readonly showPassword2: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /**
+     * Emits the current form result to trigger the password-reset flow.
+     */
+    protected ok(): void;
+    /**
+     * Generates a random password and populates both password fields with it.
+     */
+    protected generatePassword(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ResetPasswordDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ResetPasswordDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+interface RecoverPasswordDialogData {
+    appearance?: MatFormFieldAppearance;
+}
+declare class RecoverPasswordDialogComponent {
+    /** Emitted when the user submits the recovery request. Carries the entered email and recaptcha state. */
+    readonly done: _angular_core.OutputEmitterRef<RecoverPasswordDialogResult>;
+    /** Dialog configuration with defaults applied at construction time. */
+    protected readonly dialogData: _angular_core.WritableSignal<RecoverPasswordDialogData>;
+    /** Current form model bound to the template inputs. */
+    protected item: RecoverPasswordDialogResult;
+    /**
+     * Emits the current form result to trigger the password-recovery flow.
+     */
+    protected ok(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RecoverPasswordDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RecoverPasswordDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+declare class PromptOtpDialogComponent {
+    readonly f: _angular_core.Signal<NgForm>;
+    readonly done: _angular_core.OutputEmitterRef<PromptOtpDialogResult>;
+    private readonly dialogService;
+    protected readonly dialogData: _angular_core.WritableSignal<PromptDialogData>;
+    protected value: any;
+    /**
+     * Validates the form and emits the OTP result, or shows an error if validation fails.
+     */
+    protected ok(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PromptOtpDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PromptOtpDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+export { CredentialsDialogComponent, OtpInputComponent, PasswordStrengthComponent, PromptOtpDialogComponent, RecoverPasswordDialogComponent, ResetPasswordDialogComponent };
+export type { CredentialsDialogData, RecoverPasswordDialogData, ResetPasswordDialogData, ResetPasswordDialogMode };

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

@@ -0,0 +1,228 @@
+import * as _angular_core from '@angular/core';
+import { ComponentType } from '@angular/cdk/portal';
+import { MatDialogConfig, MatDialogRef } from '@angular/material/dialog';
+import { MatSnackBarRef } from '@angular/material/snack-bar';
+import { ShellService } from '@arsedizioni/ars-utils/ui.shell';
+import { DialogResult, DialogOption } from '@arsedizioni/ars-utils/ui';
+import { MatFormFieldAppearance } from '@angular/material/form-field';
+
+interface ConfirmDialogOption extends DialogOption {
+}
+interface ConfirmDialogData {
+    title?: string;
+    message: string;
+    okCaption?: string;
+    cancelCaption?: string;
+    otherCaption?: string;
+    options?: ConfirmDialogOption[];
+    details?: string;
+}
+declare class ConfirmDialogComponent {
+    /** Emitted when the user makes a choice. Carries the selected result and any option state. */
+    readonly choosen: _angular_core.OutputEmitterRef<DialogResult>;
+    private readonly dialogRef;
+    /** Dialog configuration, with sensible defaults applied at construction time. */
+    protected readonly dialogData: _angular_core.WritableSignal<ConfirmDialogData>;
+    constructor();
+    /**
+     * Confirms the dialog, emitting `'ok'` together with the current option selections.
+     */
+    ok(): void;
+    /**
+     * Cancels the dialog, emitting `'cancel'`.
+     */
+    cancel(): void;
+    /**
+     * Triggers the tertiary action, emitting `'other'`.
+     */
+    other(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ConfirmDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ConfirmDialogComponent, "ng-component", never, {}, { "choosen": "choosen"; }, never, never, true, never>;
+}
+
+declare enum DeleteDialogConfirmMode {
+    None = 0,
+    Simple = 1,
+    Strong = 2
+}
+interface DeleteDialogData {
+    title?: string;
+    message: string;
+    confirmMode: DeleteDialogConfirmMode;
+    okCaption?: string;
+    cancelCaption?: string;
+    details?: string;
+    appearance?: MatFormFieldAppearance;
+}
+declare class DeleteDialogComponent {
+    /** Emitted when the user makes a choice. Carries the selected result. */
+    readonly choosen: _angular_core.OutputEmitterRef<DialogResult>;
+    private readonly dialogRef;
+    /** Dialog configuration with defaults applied at construction time. */
+    protected readonly dialogData: _angular_core.WritableSignal<DeleteDialogData>;
+    /**
+     * Whether the user has confirmed the deletion.
+     * Starts as `true` for all modes except `Simple`, which requires explicit checkbox confirmation.
+     */
+    protected readonly confirmed: _angular_core.WritableSignal<boolean>;
+    /** Current value typed into the strong-confirmation text field. */
+    protected confirmValue?: string;
+    /**
+     * Confirms the deletion, emitting `'ok'` and closing the dialog.
+     */
+    ok(): void;
+    /**
+     * Cancels the operation, emitting `'cancel'` and closing the dialog.
+     */
+    cancel(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DeleteDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DeleteDialogComponent, "ng-component", never, {}, { "choosen": "choosen"; }, never, never, true, never>;
+}
+
+interface ToastData {
+    message: string;
+    icon?: string;
+    actionCaption?: string;
+}
+declare class ToastComponent {
+    /** Emitted when the user clicks the optional action button. */
+    readonly action: _angular_core.OutputEmitterRef<void>;
+    /** Snack-bar payload with a safe fallback to an empty message when no data is injected. */
+    protected readonly dialogData: _angular_core.WritableSignal<ToastData>;
+    /**
+     * Emits the `action` event to notify the caller that the action button was clicked.
+     */
+    protected do(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToastComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ToastComponent, "ng-component", never, {}, { "action": "action"; }, never, never, true, never>;
+}
+
+interface IDialogService {
+}
+declare class DialogService extends ShellService {
+    private readonly uiService;
+    /**
+     * Shares the SAME `appearance` signal instance as the root `UIService`:
+     * `uiService.setAppearance('outline')` is immediately visible here and in
+     * every dialog opened by this service.
+     *
+     * Held by delegation and no longer by inheritance: this service now extends `ShellService`,
+     * which knows nothing about Material and must not, so the two members every caller uses of
+     * `UIService` are re-exposed here.
+     */
+    readonly appearance: _angular_core.WritableSignal<"fill" | "outline">;
+    /**
+     * Updates the global form-field appearance.
+     * @param value - The new appearance value. Falls back to `'fill'` when `undefined` is passed.
+     * @returns void
+     */
+    setAppearance(value: 'fill' | 'outline' | undefined): void;
+    private readonly dialog;
+    private readonly snackBar;
+    private readonly location;
+    private readonly popHistory;
+    private popState;
+    private poppingState;
+    constructor();
+    /**
+     * Lets the next `popstate` through without closing the topmost dialog.
+     *
+     * Back closing the dialog on top is the rule of this service, and its listener is registered in
+     * the constructor — so nothing attached later can get in front of it. A caller that owns a
+     * dismissable state of its own INSIDE a dialog (a full-screen editor, a picker covering the
+     * dialog, a wizard step) needs Back to unwind that state first, and this is the only way to ask
+     * for it: push a history entry, call this, and handle the pop.
+     *
+     * The suspension lasts exactly one `popstate` and is consumed whether or not the caller pushed
+     * an entry, so it can not leave the service permanently deaf to the Back button.
+     */
+    suspendBackClose(): void;
+    /**
+     * Removes trailing `#` characters from the current URL (e.g. after a page reload).
+     * @param resetPoppingState - When `true`, resets the internal popping-state flag.
+     */
+    clearUrl(resetPoppingState?: boolean): void;
+    /**
+     * Close all dialogs
+     */
+    closeAll(): void;
+    /**
+     * Opens a Material dialog. Returns `null` when not running in a browser.
+     * @param component - The component to open as a dialog.
+     * @param config   - The dialog configuration.
+     * @returns The dialog reference, or `null` outside the browser.
+     */
+    open<T>(component: ComponentType<T>, config: MatDialogConfig<unknown>): MatDialogRef<T> | null;
+    /**
+     * Internal helper that wraps `MatDialog.open`, subscribes to lifecycle hooks
+     * and manages browser-history push/pop entries.
+     * @param component - The component to open.
+     * @param config   - The dialog configuration.
+     * @returns The dialog reference.
+     */
+    private openDialog;
+    /**
+     * Returns the element height including margins
+     * @param element - element
+     * @returns the height
+     */
+    private outerHeight;
+    /**
+     * Return current dialog height
+     */
+    getCurrentDialogHeight(): number;
+    /**
+     * Returns the scrollable content area height for the topmost open dialog.
+     * @param fixedPartsClassName - CSS class names of fixed (non-scrollable) elements whose heights are subtracted.
+     * @param minimalHeight       - Minimum height floor to use when the dialog height is smaller.
+     * @returns The computed scrollable height in pixels.
+     */
+    getCurrentDialogScrollableHeight(fixedPartsClassName: string[], minimalHeight: number): number;
+    /**
+     * Push a dialog into the browser history
+     */
+    private pushDialog;
+    /**
+     * Pop a dialog from the history
+     */
+    private popDialog;
+    /**
+     * Shows a snack-bar toast notification.
+     * @param message       - HTML message to display.
+     * @param duration      - Visible duration in milliseconds. Defaults to `2000`.
+     * @param icon          - Material icon name shown beside the message. Defaults to `'check'`.
+     * @param actionCaption - Optional label for the action button.
+     * @returns The snack-bar reference.
+     */
+    toast(message: string, duration?: number, icon?: string, actionCaption?: string): MatSnackBarRef<ToastComponent>;
+    /**
+     * Opens a confirmation dialog.
+     * @param message       - HTML message to display.
+     * @param title         - Dialog title. Defaults to `'Conferma'`.
+     * @param okCaption     - Primary action button label. Defaults to `'Si'`.
+     * @param cancelCaption - Cancel button label. Defaults to `'No'`.
+     * @param otherCaption  - Optional tertiary action button label.
+     * @param options       - Optional list of checkbox options shown to the user.
+     * @param width         - Maximum dialog width in pixels. Defaults to `500`.
+     * @param details       - Optional secondary details text.
+     * @returns The dialog reference, or `null` outside the browser.
+     */
+    confirm(message: string, title?: string, okCaption?: string, cancelCaption?: string, otherCaption?: string, options?: ConfirmDialogOption[], width?: number, details?: string): MatDialogRef<ConfirmDialogComponent> | null;
+    /**
+     * Opens a deletion-confirmation dialog.
+     * @param message       - HTML message to display.
+     * @param title         - Dialog title. Defaults to `'Attenzione'`.
+     * @param confirmMode   - Confirmation mode (none / checkbox / type-to-confirm). Defaults to `None`.
+     * @param okCaption     - Primary action button label. Defaults to `'Si'`.
+     * @param cancelCaption - Cancel button label. Defaults to `'No'`.
+     * @param width         - Maximum dialog width in pixels. Defaults to `500`.
+     * @param details       - Optional secondary details text.
+     * @returns The dialog reference, or `null` outside the browser.
+     */
+    delete(message: string, title?: string, confirmMode?: DeleteDialogConfirmMode, okCaption?: string, cancelCaption?: string, width?: number, details?: string): MatDialogRef<DeleteDialogComponent> | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DialogService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<DialogService>;
+}
+
+export { ConfirmDialogComponent, DeleteDialogComponent, DeleteDialogConfirmMode, DialogService, ToastComponent };
+export type { ConfirmDialogData, ConfirmDialogOption, DeleteDialogData, IDialogService, ToastData };

package/types/arsedizioni-ars-utils-ui.dialogs.prompt.d.ts

@@ -0,0 +1,47 @@
+import * as _angular_core from '@angular/core';
+import { PromptDialogResult, PromptDialogData, PromptDateDialogResult, PromptTimeDialogData } from '@arsedizioni/ars-utils/ui';
+import { NgForm } from '@angular/forms';
+
+declare class PromptDialogComponent {
+    readonly f: _angular_core.Signal<NgForm>;
+    readonly done: _angular_core.OutputEmitterRef<PromptDialogResult>;
+    private readonly dialogService;
+    protected readonly dialogData: _angular_core.WritableSignal<PromptDialogData>;
+    protected value: any;
+    /**
+     * Validates the form and emits the result, or shows an error if validation fails.
+     */
+    protected ok(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PromptDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PromptDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+declare class PromptDateDialogComponent {
+    readonly f: _angular_core.Signal<NgForm>;
+    readonly done: _angular_core.OutputEmitterRef<PromptDateDialogResult>;
+    private readonly dialogService;
+    protected readonly dialogData: _angular_core.WritableSignal<PromptDialogData>;
+    protected value: any;
+    /**
+     * Validates the form and emits the result, or shows an error if validation fails.
+     */
+    protected ok(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PromptDateDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PromptDateDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+declare class PromptTimeDialogComponent {
+    readonly f: _angular_core.Signal<NgForm>;
+    readonly done: _angular_core.OutputEmitterRef<PromptDialogResult>;
+    private readonly dialogService;
+    protected readonly dialogData: _angular_core.WritableSignal<PromptTimeDialogData>;
+    protected value: any;
+    /**
+     * Validates the form and emits the result, or shows an error if validation fails.
+     */
+    protected ok(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PromptTimeDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PromptTimeDialogComponent, "ng-component", never, {}, { "done": "done"; }, never, never, true, never>;
+}
+
+export { PromptDateDialogComponent, PromptDialogComponent, PromptTimeDialogComponent };