ng-hub-ui-loading 22.0.0

package/types/ng-hub-ui-loading.d.ts

@@ -0,0 +1,252 @@
+import * as _angular_core from '@angular/core';
+import { Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
+
+/**
+ * Where the indicator is placed relative to the document.
+ *
+ * `overlay` positions absolutely, so the **parent must establish a containing
+ * block** (`position: relative`); `fullscreen` is fixed to the viewport and is
+ * what {@link HubLoadingService} mounts on `document.body`.
+ */
+type HubLoadingMode = 'inline' | 'overlay' | 'fullscreen';
+/** Built-in pure-CSS activity indicators, so the library ships no image assets. */
+type HubLoadingVariant = 'spinner' | 'dots' | 'bars' | 'pulse' | 'ring';
+/** Size step mapped to `--hub-loading-size`; the token stays overridable on its own. */
+type HubLoadingSize = 'sm' | 'md' | 'lg';
+/** Motion applied to a branding image that replaces the built-in indicator. */
+type HubLoadingImageAnimation = 'none' | 'spin' | 'pulse';
+/**
+ * Per-call presentation options accepted by {@link HubLoadingService}.
+ *
+ * Every field is optional: omitted values fall back to the application-wide
+ * {@link HubLoadingConfig}, so a caller only states what it wants to change.
+ * `mode` is deliberately absent — the service always renders fullscreen.
+ */
+interface HubLoadingOptions {
+    /** Text rendered under the indicator; `null` renders no message. */
+    message?: string | null;
+    /** Which built-in indicator to render when no {@link image} is supplied. */
+    variant?: HubLoadingVariant;
+    /** URL or data URI replacing the built-in indicator with a brand mark. */
+    image?: string | null;
+    /** Motion applied to {@link image}; ignored when no image is set. */
+    imageAnimation?: HubLoadingImageAnimation;
+    /** Size step driving `--hub-loading-size`. */
+    size?: HubLoadingSize;
+    /** Accent colour: a semantic name, a hex/`oklch()` literal or a `var(...)` reference. */
+    color?: string | null;
+    /** Paints the translucent scrim; honoured in overlay and fullscreen modes only. */
+    backdrop?: boolean;
+    /** Accessible label announced through `role="status"`. */
+    ariaLabel?: string;
+}
+/**
+ * Application-wide defaults for every loading indicator.
+ *
+ * Fully resolved (no optional members) so the component and the service can read
+ * a value without re-implementing the fallback chain at each call site.
+ */
+interface HubLoadingConfig {
+    /** Default text under the indicator. */
+    message: string | null;
+    /** Default built-in indicator. */
+    variant: HubLoadingVariant;
+    /** Default branding image, if the whole application uses one. */
+    image: string | null;
+    /** Default motion for the branding image. */
+    imageAnimation: HubLoadingImageAnimation;
+    /** Default size step. */
+    size: HubLoadingSize;
+    /** Default accent colour, or `null` to keep the stylesheet's own accent. */
+    color: string | null;
+    /** Default scrim visibility for overlay and fullscreen modes. */
+    backdrop: boolean;
+    /** Default accessible label. */
+    ariaLabel: string;
+}
+
+/**
+ * Activity indicator rendered inline, over its container or over the viewport.
+ *
+ * Every input defaults to the injected `HUB_LOADING_CONFIG`, so `provideHubLoading()`
+ * re-bases an entire application (brand image, variant, translated label) without
+ * touching a single template, while a per-instance binding still wins locally.
+ *
+ * Styles are unencapsulated on purpose: the host carries the `hub-loading` class and
+ * the token block, so consumers can retheme the indicator from a global stylesheet —
+ * and so the service-mounted overlay, created outside any component's style scope,
+ * is still painted.
+ *
+ * @example
+ * ```html
+ * <hub-loading variant="dots" message="Loading orders…" />
+ *
+ * <div style="position: relative">
+ *   <hub-loading mode="overlay" color="primary" />
+ * </div>
+ * ```
+ */
+declare class HubLoadingComponent {
+    /** Application-wide defaults; also the source of every input's default value. */
+    private readonly config;
+    /**
+     * Placement of the indicator. `overlay` needs a positioned ancestor to cover;
+     * `fullscreen` is fixed to the viewport and layered at `--hub-loading-z-index`.
+     */
+    readonly mode: _angular_core.InputSignal<HubLoadingMode>;
+    /** Built-in CSS indicator rendered when no {@link image} is supplied. */
+    readonly variant: _angular_core.InputSignal<HubLoadingVariant>;
+    /** URL or data URI shown instead of the built-in indicator. */
+    readonly image: _angular_core.InputSignal<string | null>;
+    /** Motion applied to {@link image}; inert while no image is set. */
+    readonly imageAnimation: _angular_core.InputSignal<HubLoadingImageAnimation>;
+    /** Text rendered below the indicator. */
+    readonly message: _angular_core.InputSignal<string | null>;
+    /** Size step feeding `--hub-loading-size`; the token remains overridable on its own. */
+    readonly size: _angular_core.InputSignal<HubLoadingSize>;
+    /**
+     * Accent for the indicator. Accepts a semantic name (`primary`), a CSS colour
+     * literal (`#0d6efd`, `oklch(...)`) or a `var(...)` reference — normalised by
+     * `resolveHubAccent()` into the single `--hub-loading-accent` slot.
+     */
+    readonly color: _angular_core.InputSignal<string | null>;
+    /** Paints the translucent scrim. Ignored in `inline` mode, which covers nothing. */
+    readonly backdrop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accessible label announced by the host's `role="status"` live region. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Mode and size modifiers; kept as one binding so a size change cannot drop the mode. */
+    protected readonly _modifierClasses: _angular_core.Signal<string>;
+    /**
+     * The scrim only exists where the indicator actually covers something, so an
+     * inline block never paints a background it would have no reason to own.
+     */
+    protected readonly _showsBackdrop: _angular_core.Signal<boolean>;
+    /**
+     * Single accent slot consumed by the stylesheet. `null` leaves the binding off
+     * entirely, so the token's own cascade default stays in effect.
+     */
+    protected readonly _accent: _angular_core.Signal<string | null>;
+    /** Motion modifier for the branding image; `none` adds no class at all. */
+    protected readonly _imageClasses: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubLoadingComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubLoadingComponent, "hub-loading", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "image": { "alias": "image"; "required": false; "isSignal": true; }; "imageAnimation": { "alias": "imageAnimation"; "required": false; "isSignal": true; }; "message": { "alias": "message"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "backdrop": { "alias": "backdrop"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Drives a single application-wide fullscreen loading overlay.
+ *
+ * Concurrency is handled with a reference counter rather than a boolean, because
+ * independent callers overlap constantly (two parallel requests, a resolver plus a
+ * component): the overlay appears on the first `show()` and only disappears once
+ * every caller has balanced it with a `hide()`. A caller that forgets to hide would
+ * strand the overlay, so {@link hideAll} exists as the explicit escape hatch — use it
+ * from an error handler or a route change, never as a substitute for balanced calls.
+ *
+ * Server-side there is no DOM to mount into, so only the counter runs: `isLoading`
+ * stays truthful and hydration finds no orphan overlay markup.
+ *
+ * @example
+ * ```typescript
+ * private readonly loading = inject(HubLoadingService);
+ *
+ * async save(): Promise<void> {
+ *   this.loading.show({ message: 'Saving…' });
+ *   try {
+ *     await this.api.save();
+ *   } finally {
+ *     this.loading.hide();
+ *   }
+ * }
+ * ```
+ */
+declare class HubLoadingService {
+    private readonly appRef;
+    private readonly document;
+    private readonly platformId;
+    private readonly config;
+    /** Number of callers currently requesting the overlay. */
+    private readonly pending;
+    /** Live reference to the mounted overlay; `null` whenever nothing is showing. */
+    private overlayRef;
+    /**
+     * Options accumulated by the active `show()` / `update()` calls, layered over
+     * `HUB_LOADING_CONFIG`. Reset once the counter reaches zero so a later overlay
+     * never inherits a stale message from a finished operation.
+     */
+    private options;
+    /** True while at least one caller is still waiting. Safe to read during SSR. */
+    readonly isLoading: Signal<boolean>;
+    /**
+     * Registers one caller and mounts the overlay if it is not up yet.
+     *
+     * @param options - Presentation overrides merged over the application defaults;
+     * only the keys supplied are changed, so nested calls compose instead of resetting.
+     */
+    show(options?: HubLoadingOptions): void;
+    /**
+     * Retires one caller, tearing the overlay down once none are left.
+     * Extra calls are harmless: the counter is clamped at zero rather than going
+     * negative, so a stray `hide()` cannot make a later `show()` a no-op.
+     */
+    hide(): void;
+    /** Drops every pending caller and removes the overlay immediately. */
+    hideAll(): void;
+    /**
+     * Re-dresses the overlay while it stays up — a progress message that changes
+     * mid-operation, a variant swap — without touching the reference counter.
+     *
+     * @param options - Presentation overrides merged over the active ones.
+     */
+    update(options: HubLoadingOptions): void;
+    /**
+     * Copies only the keys the caller actually supplied.
+     *
+     * A plain spread would let an `undefined` property erase a configured default,
+     * which would make `{ message: undefined }` and `{ message: null }` behave the
+     * same; here `undefined` means "leave it alone" and `null` means "clear it".
+     */
+    private mergeOptions;
+    /**
+     * Creates the overlay on `document.body` once, outside any component subtree, so
+     * it is never clipped by an ancestor's `overflow` or stacking context.
+     */
+    private mount;
+    /** Destroys the overlay and forgets the accumulated options. */
+    private unmount;
+    /**
+     * Pushes the resolved options onto the overlay.
+     *
+     * Change detection is run by hand: a view attached through `attachView()` sits
+     * outside the signal graph's "mark ancestors dirty" traversal, so it would not
+     * repaint on its own when an input changes.
+     */
+    private applyOptions;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubLoadingService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<HubLoadingService>;
+}
+
+/**
+ * Neutral defaults applied when an application provides no configuration.
+ *
+ * These are the values documented as each input's default, so overriding the
+ * token silently re-bases the whole application without touching a template.
+ */
+declare const HUB_LOADING_DEFAULT_CONFIG: HubLoadingConfig;
+/**
+ * Resolved defaults shared by `<hub-loading>` and `HubLoadingService`.
+ *
+ * Declared with a root factory so the token is always injectable, even when the
+ * application never calls {@link provideHubLoading}.
+ */
+declare const HUB_LOADING_CONFIG: InjectionToken<HubLoadingConfig>;
+/**
+ * Registers application-wide loading defaults — typically the brand image, the
+ * preferred variant and a translated label — so individual call sites stay bare.
+ *
+ * @param config - Values overriding {@link HUB_LOADING_DEFAULT_CONFIG}; omitted keys keep their default.
+ * @returns Environment providers for the application bootstrap.
+ */
+declare function provideHubLoading(config?: Partial<HubLoadingConfig>): EnvironmentProviders;
+
+export { HUB_LOADING_CONFIG, HUB_LOADING_DEFAULT_CONFIG, HubLoadingComponent, HubLoadingService, provideHubLoading };
+export type { HubLoadingConfig, HubLoadingImageAnimation, HubLoadingMode, HubLoadingOptions, HubLoadingSize, HubLoadingVariant };