@nexterajs/ui 0.0.1 → 0.1.0

package/types/nexterajs-ui-notify.d.ts

@@ -0,0 +1,149 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { SafeHtml } from '@angular/platform-browser';
+import { NxeMessageService } from '@nexterajs/ui/core';
+
+type NxeToastType = 'success' | 'error' | 'warning' | 'info';
+type NxeToastPosition = 'toast-top-center' | 'toast-bottom-center' | 'toast-top-right' | 'toast-bottom-right' | 'toast-top-left' | 'toast-bottom-left' | 'toast-top-full-width' | 'toast-bottom-full-width';
+/** Per-call options. Anything omitted falls back to the global {@link NxeToastConfig}. */
+interface NxeToastOverride {
+    /**
+     * Render the message as HTML rather than text.
+     *
+     * The message is still sanitised. Callers pass server-composed strings here — a list of
+     * validation failures joined with `<br>` — so the markup is not author-controlled and must not
+     * be trusted, but stripping it entirely would collapse those lists onto one line.
+     */
+    enableHtml?: boolean;
+    /** Dismiss when the body is clicked. The close button works regardless. */
+    tapToDismiss?: boolean;
+    /** Milliseconds before auto-dismiss. `0` keeps it up until dismissed. */
+    timeOut?: number;
+    closeButton?: boolean;
+    progressBar?: boolean;
+    /** Extra classes on the toast element. */
+    toastClass?: string;
+    titleClass?: string;
+    messageClass?: string;
+}
+interface NxeToastConfig extends NxeToastOverride {
+    /** Which corner or edge the stack is anchored to. */
+    positionClass?: NxeToastPosition;
+    /**
+     * Put the newest toast at the top of the stack.
+     *
+     * Defaults to true, matching the library this replaces. A naive appending list reverses it —
+     * visibly, and without any test failing.
+     */
+    newestOnTop?: boolean;
+    /** Drop a toast whose type, title and message match one already showing. */
+    preventDuplicates?: boolean;
+    /** Cap the stack; 0 means no cap. Older toasts are dismissed first. */
+    maxOpened?: number;
+}
+declare const NXE_TOAST_DEFAULTS: Required<Pick<NxeToastConfig, 'positionClass' | 'timeOut' | 'closeButton' | 'progressBar' | 'tapToDismiss' | 'enableHtml' | 'newestOnTop' | 'preventDuplicates' | 'maxOpened'>>;
+declare const NXE_TOAST_CONFIG: InjectionToken<NxeToastConfig>;
+
+/**
+ * One toast. Rendered by {@link NxeToastService} into its container; not used directly.
+ *
+ * **The element order is load-bearing.** The close button comes first and is floated right, which
+ * is how the library this replaces positioned it — move it after the title and it drops below the
+ * text instead of sitting in the corner. Likewise the host carries the classes rather than an
+ * inner wrapper, because the shipped stylesheet targets `.nxe-toast-container .nxe-toast`
+ * directly and an extra element between them changes what `width` and `margin` apply to.
+ *
+ * Styles are global (`@nexterajs/ui/styles/_toast.scss`), not encapsulated, so an application's
+ * existing overrides keep winning on specificity exactly as they did before.
+ *
+ * Accessibility, which the original had none of:
+ * - `error` and `warning` announce as `alert` (assertive — the user's own action caused it).
+ *   `success` and `info` announce as `status` (polite).
+ * - Focus is never taken. A validation toast typically appears mid-keystroke, and moving focus
+ *   would pull the caret out of the field being corrected.
+ * - The close button is a real `<button>` with a label, reachable by keyboard.
+ */
+declare class NxeToastComponent {
+    protected readonly messages: NxeMessageService;
+    private readonly sanitizer;
+    readonly type: _angular_core.InputSignal<NxeToastType>;
+    readonly title: _angular_core.InputSignal<string | null>;
+    readonly message: _angular_core.InputSignal<string | null>;
+    readonly enableHtml: _angular_core.InputSignal<boolean>;
+    readonly tapToDismiss: _angular_core.InputSignal<boolean>;
+    readonly closeButton: _angular_core.InputSignal<boolean>;
+    readonly progressBar: _angular_core.InputSignal<boolean>;
+    readonly toastClass: _angular_core.InputSignal<string>;
+    readonly titleClass: _angular_core.InputSignal<string>;
+    readonly messageClass: _angular_core.InputSignal<string>;
+    readonly dismissed: _angular_core.OutputEmitterRef<void>;
+    /** Pre-enter state: the service clears it a frame later so the opacity transition runs. */
+    readonly entering: _angular_core.WritableSignal<boolean>;
+    /** Set while the leave transition plays; the service removes the view once it finishes. */
+    readonly dismissing: _angular_core.WritableSignal<boolean>;
+    readonly progressWidth: _angular_core.WritableSignal<number>;
+    protected readonly assertive: _angular_core.Signal<boolean>;
+    protected readonly hostClass: _angular_core.Signal<string>;
+    /**
+     * Sanitised HTML for the message.
+     *
+     * Callers pass server-composed strings here — validation failures joined with `<br>` — so this
+     * is data, not markup the application authored. `sanitize` drops anything executable and keeps
+     * the line breaks the lists depend on.
+     */
+    protected readonly safeMessage: _angular_core.Signal<SafeHtml>;
+    protected onBodyClick(): void;
+    protected onCloseClick(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeToastComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeToastComponent, "nxe-toast", never, { "type": { "alias": "type"; "required": true; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "message": { "alias": "message"; "required": false; "isSignal": true; }; "enableHtml": { "alias": "enableHtml"; "required": false; "isSignal": true; }; "tapToDismiss": { "alias": "tapToDismiss"; "required": false; "isSignal": true; }; "closeButton": { "alias": "closeButton"; "required": false; "isSignal": true; }; "progressBar": { "alias": "progressBar"; "required": false; "isSignal": true; }; "toastClass": { "alias": "toastClass"; "required": false; "isSignal": true; }; "titleClass": { "alias": "titleClass"; "required": false; "isSignal": true; }; "messageClass": { "alias": "messageClass"; "required": false; "isSignal": true; }; }, { "dismissed": "dismissed"; }, never, never, true, never>;
+}
+
+/** Handle on a shown toast. `dismiss()` is safe to call more than once. */
+interface NxeToastRef {
+    dismiss(): void;
+    readonly type: NxeToastType;
+    readonly title: string | null;
+    readonly message: string | null;
+}
+/**
+ * Configure the toast stack once, at bootstrap.
+ *
+ * ```ts
+ * providers: [provideNxeToast({ positionClass: 'toast-top-center' })]
+ * ```
+ */
+declare function provideNxeToast(config?: NxeToastConfig): EnvironmentProviders;
+/**
+ * Shows toasts.
+ *
+ * **The container is deliberately not a CDK overlay.** A CDK overlay pane lands in the same
+ * `.cdk-overlay-container` as the application's dialogs, which makes paint order creation order —
+ * so a toast raised right after a dialog closes can end up behind the next dialog that opens.
+ * Callers do exactly that. A dedicated container with its own stacking context keeps toasts above
+ * dialogs regardless of the order things were created in.
+ */
+declare class NxeToastService {
+    private readonly appRef;
+    private readonly injector;
+    private readonly document;
+    private readonly userConfig;
+    private readonly config;
+    private container;
+    private readonly active;
+    success(message?: string | null, title?: string | null, override?: NxeToastOverride): NxeToastRef;
+    error(message?: string | null, title?: string | null, override?: NxeToastOverride): NxeToastRef;
+    warning(message?: string | null, title?: string | null, override?: NxeToastOverride): NxeToastRef;
+    info(message?: string | null, title?: string | null, override?: NxeToastOverride): NxeToastRef;
+    /** Dismiss everything currently showing. */
+    clear(): void;
+    show(type: NxeToastType, message?: string | null, title?: string | null, override?: NxeToastOverride): NxeToastRef;
+    /** Shrink the progress bar across the toast's lifetime, the way the original drove it. */
+    private runProgress;
+    private remove;
+    private ensureContainer;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeToastService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NxeToastService>;
+}
+
+export { NXE_TOAST_CONFIG, NXE_TOAST_DEFAULTS, NxeToastComponent, NxeToastService, provideNxeToast };
+export type { NxeToastConfig, NxeToastOverride, NxeToastPosition, NxeToastRef, NxeToastType };