ng-hub-ui-loading 22.0.0 → 22.1.0

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

@@ -1,5 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
+import { HttpContextToken, HttpInterceptorFn, HttpContext } from '@angular/common/http';
 
 /**
  * Where the indicator is placed relative to the document.
@@ -248,5 +249,408 @@ declare const HUB_LOADING_CONFIG: InjectionToken<HubLoadingConfig>;
  */
 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 };
+/**
+ * Where the bar is placed relative to the document.
+ *
+ * `inline` takes part in normal flow and reserves its own strip, so the page never
+ * shifts when the bar appears; `overlay` is absolutely positioned against the nearest
+ * positioned ancestor — the classic "hanging off the bottom edge of a navbar" case, and
+ * the consumer owns that containing block; `fixed` pins the bar to the viewport, offset
+ * by `--hub-loading-bar-offset` so it can sit under a navbar that is itself fixed.
+ */
+type HubLoadingBarMode = 'inline' | 'overlay' | 'fixed';
+/** Which edge the `overlay` and `fixed` modes attach to; ignored by `inline`. */
+type HubLoadingBarPlacement = 'top' | 'bottom';
+/**
+ * Function deciding how much to advance on each trickle tick.
+ *
+ * Page loads have no honest percentage — the browser does not know how many bytes are
+ * left, and a resolver knows even less. The bar therefore advances in steps that shrink
+ * as it fills, so it always seems to be moving while never reaching the end on its own.
+ *
+ * @param progress - Current value, 0–100.
+ * @returns Amount to add, in the same 0–100 scale. Return `0` to stall.
+ */
+type HubLoadingBarTrickle = (progress: number) => number;
+/**
+ * Application-wide defaults for the loading bar.
+ *
+ * Fully resolved (no optional members) so the component, the service and the
+ * integrations read a value without re-implementing the fallback chain at each call site.
+ * Durations are milliseconds; progress values are on a 0–100 scale.
+ */
+interface HubLoadingBarConfig {
+    /**
+     * Value the bar jumps to the instant it appears.
+     *
+     * Never zero: a bar that starts empty reads as a bar that is not working. The jump is
+     * the acknowledgement that the request was received.
+     */
+    min: number;
+    /**
+     * Ceiling the trickle may not cross.
+     *
+     * Below 100 on purpose. Only {@link HubLoadingBarService.complete} knows the work is
+     * actually done, so a trickle that reached 100 would promise an ending it cannot
+     * deliver and then sit there, full and lying.
+     */
+    max: number;
+    /** Milliseconds between trickle ticks. */
+    trickleSpeed: number;
+    /** Whether the bar advances on its own while it waits. */
+    trickle: boolean;
+    /** Step function driving each tick; see {@link HubLoadingBarTrickle}. */
+    trickleFn: HubLoadingBarTrickle;
+    /**
+     * Grace period before the bar is painted at all.
+     *
+     * Work that finishes inside this window never shows a bar. A 40 ms navigation that
+     * flashes a progress bar looks broken, not fast — this is what keeps a cached route
+     * from flickering.
+     *
+     * `0` reveals the bar synchronously rather than on the next macrotask, so a caller who
+     * opted out of the grace period still sees it for work that settles within its own task.
+     */
+    delay: number;
+    /**
+     * How long the completed bar stays on screen at 100% before it fades away.
+     *
+     * Wants to be at least `--hub-loading-bar-speed`, or the bar is dismissed before its
+     * own fill animation has arrived at the end.
+     */
+    completeDelay: number;
+    /** Default accent: a semantic name, a colour literal or a `var(...)` reference. */
+    color: string | null;
+    /** Whether the leading edge carries the soft glow that suggests motion. */
+    glow: boolean;
+    /** Accessible name announced through `role="progressbar"`. */
+    ariaLabel: string;
+}
+
+/**
+ * The thin strip that reports page-level progress — the bar under the navbar.
+ *
+ * By default the component draws whatever {@link HubLoadingBarService} is doing, which is
+ * what makes a single `<hub-loading-bar />` in the shell enough for the whole
+ * application: the router integration and the HTTP interceptor drive the service, and
+ * this element follows. Bind `progress` to take it over instead, for a bar reporting one
+ * known quantity — an upload, an import — independently of everything else.
+ *
+ * The `progress` input therefore has three meanings, and the difference matters:
+ * unbound (`undefined`) follows the service; a number drives the bar directly; `null`
+ * hides it. This mirrors how `HubLoadingService` already reads `undefined` as "leave it
+ * alone" and `null` as "clear it".
+ *
+ * Note the deliberate gap in the accessibility contract. While the service is trickling,
+ * the number on screen is invented — nothing knows the real percentage of a page load —
+ * so `aria-valuenow` is withheld, which is exactly how ARIA spells an indeterminate
+ * progressbar. Announcing a made-up "43%" would be worse than announcing nothing. The
+ * value is published only when a caller has bound a real one.
+ *
+ * Styles are unencapsulated, like the rest of the library, so a consumer can retheme the
+ * bar from a global stylesheet.
+ *
+ * @example
+ * ```html
+ * <!-- Hanging off the bottom edge of a navbar, driven by the service -->
+ * <nav class="navbar position-relative">
+ *   …
+ *   <hub-loading-bar mode="overlay" placement="bottom" />
+ * </nav>
+ *
+ * <!-- Reporting one known quantity -->
+ * <hub-loading-bar [progress]="uploaded()" color="success" />
+ * ```
+ */
+declare class HubLoadingBarComponent {
+    /** Application-wide defaults; also the source of every input's default value. */
+    private readonly config;
+    /** The shared page-level state this bar renders unless `progress` is bound. */
+    private readonly service;
+    /**
+     * Placement of the strip. `overlay` needs a positioned ancestor to attach to;
+     * `fixed` pins it to the viewport at `--hub-loading-bar-offset`.
+     */
+    readonly mode: _angular_core.InputSignal<HubLoadingBarMode>;
+    /** Edge the `overlay` and `fixed` modes attach to; `inline` ignores it. */
+    readonly placement: _angular_core.InputSignal<HubLoadingBarPlacement>;
+    /**
+     * Takes the bar over. Leave it unbound to follow {@link HubLoadingBarService}; bind a
+     * number (0–100) to drive it directly, or `null` to hide it.
+     */
+    readonly progress: _angular_core.InputSignal<number | null | undefined>;
+    /**
+     * Sweeps a fragment back and forth instead of filling.
+     *
+     * The honest choice when there is no percentage worth inventing — a long stream, a
+     * job with no reported stages.
+     */
+    readonly indeterminate: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Soft glow trailing the leading edge, which is what reads as movement. */
+    readonly glow: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Accent for the fill. Accepts a semantic name (`primary`), a CSS colour literal or a
+     * `var(...)` reference — normalised by `resolveHubAccent()` into the single
+     * `--hub-loading-bar-accent` slot.
+     */
+    readonly color: _angular_core.InputSignal<string | null>;
+    /** Accessible name for the host's `role="progressbar"`. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Whether a caller has taken the bar over rather than following the service. */
+    private readonly _manual;
+    /** Current fill, from whichever source is in charge. */
+    private readonly _value;
+    /** Whether the strip is painted at all. */
+    protected readonly _visible: _angular_core.Signal<boolean>;
+    /** Fill as a CSS length, consumed by the stylesheet's single runtime slot. */
+    protected readonly _fill: _angular_core.Signal<string>;
+    /**
+     * The value published to assistive technology: only ever a real one.
+     *
+     * `null` removes the attribute, which is how ARIA marks a progressbar indeterminate —
+     * the correct answer both while the service trickles an invented number and while the
+     * `indeterminate` sweep is running. A bar that is not painted publishes nothing either:
+     * the host is `aria-hidden` by then, so a stale value would only ever be misleading.
+     */
+    protected readonly _announcedValue: _angular_core.Signal<number | null>;
+    /** Mode and placement modifiers; kept as one binding so neither can drop the other. */
+    protected readonly _modifierClasses: _angular_core.Signal<string>;
+    /**
+     * 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>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubLoadingBarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubLoadingBarComponent, "hub-loading-bar", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "progress": { "alias": "progress"; "required": false; "isSignal": true; }; "indeterminate": { "alias": "indeterminate"; "required": false; "isSignal": true; }; "glow": { "alias": "glow"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Drives the page-level loading bar: the thin strip under the navbar that says
+ * "something is on its way" without pretending to know how long it will take.
+ *
+ * Three decisions shape the whole service, and each exists because the naive version is
+ * worse:
+ *
+ * - **Reference counting, not a boolean.** A route change and the three requests its
+ *   page fires are four independent callers. With a boolean, the first one to finish
+ *   would take the bar down while the other three were still working. The bar completes
+ *   when the count reaches zero, and {@link completeAll} is the escape hatch for a caller
+ *   that never balanced its `start()`.
+ * - **A grace period before anything is painted.** Work that finishes within `delay`
+ *   never shows a bar at all. A cached route that flashes a progress bar for 40 ms reads
+ *   as a glitch, not as speed.
+ * - **A trickle that never reaches the end.** Nothing here knows the real percentage, so
+ *   the bar advances in shrinking steps and stops at `max`. Only `complete()` may show
+ *   100, because only `complete()` knows it is true.
+ *
+ * Timers run outside the Angular zone. Inside it, a 250 ms interval would trigger change
+ * detection for the whole application on every tick and — far worse — would keep
+ * `ApplicationRef.isStable` false forever, which hangs server-side rendering. The state
+ * is signals, so change detection is still scheduled correctly when a value actually
+ * changes. On the server no timer is created at all: the counter stays truthful and the
+ * rendered HTML carries no bar to mismatch on hydration.
+ *
+ * @example
+ * ```typescript
+ * private readonly bar = inject(HubLoadingBarService);
+ *
+ * async import(): Promise<void> {
+ *   this.bar.start();
+ *   try {
+ *     await this.api.import();
+ *   } finally {
+ *     this.bar.complete();
+ *   }
+ * }
+ * ```
+ */
+declare class HubLoadingBarService {
+    private readonly config;
+    private readonly zone;
+    private readonly platformId;
+    /** Number of callers currently waiting on something. */
+    private readonly pending;
+    /** Current fill, 0–100. */
+    private readonly _progress;
+    /** Whether the bar is painted right now; false during the grace period. */
+    private readonly _visible;
+    /** Handles of the running timers, so each can be cancelled independently. */
+    private readonly timers;
+    /** Current fill, 0–100. Bound by `<hub-loading-bar>`; safe to read during SSR. */
+    readonly progress: Signal<number>;
+    /**
+     * Whether the bar is on screen. Differs from {@link isActive} at both ends of a cycle:
+     * false while the grace period runs, and still true during the completion tail.
+     */
+    readonly isVisible: Signal<boolean>;
+    /**
+     * Whether any caller is still waiting — the honest "is the page loading?" question,
+     * regardless of whether the bar has decided to show itself yet.
+     */
+    readonly isActive: Signal<boolean>;
+    constructor();
+    /**
+     * Registers one caller. The first one starts a cycle; the rest simply join the count.
+     */
+    start(): void;
+    /**
+     * Retires one caller. Once none are left the bar runs to 100% and fades away — or, if
+     * the grace period swallowed the whole operation, disappears without ever having been
+     * seen.
+     */
+    complete(): void;
+    /** Drops every pending caller and completes the bar immediately. */
+    completeAll(): void;
+    /**
+     * Moves the bar to an exact value and reveals it, bypassing the grace period.
+     *
+     * For work whose real percentage is known — a file upload, a paged import. The value
+     * is not capped at `max`, because a caller reporting a true 100 is not guessing;
+     * finishing the cycle is still {@link complete}'s job.
+     *
+     * @param value - Target fill, 0–100. Values outside the range are clamped.
+     */
+    set(value: number): void;
+    /**
+     * Advances the bar and reveals it, bypassing the grace period.
+     *
+     * @param amount - Step to add. Omitted, the configured trickle curve decides, which is
+     * what makes an unknown wait keep moving without ever arriving.
+     */
+    inc(amount?: number): void;
+    /**
+     * Cancels everything at once: no completion animation, no pending callers, nothing on
+     * screen. For an error handler that wants the bar gone rather than finished.
+     */
+    reset(): void;
+    /** Paints the bar and starts the trickle, if a caller is waiting on one. */
+    private reveal;
+    /**
+     * Runs the completion, shared by {@link complete} and {@link completeAll}.
+     *
+     * The fill is deliberately left at 100 once the bar is hidden. `start()` rewinds it
+     * while the bar is invisible, where the stylesheet suppresses the transition, so the
+     * next cycle begins from `min` without the previous one being seen to unwind.
+     */
+    private finish;
+    /** Starts the trickle interval, unless it is disabled, already running or unneeded. */
+    private startTrickling;
+    /** Adds one step, capped at `max` so the trickle can never claim to be finished. */
+    private advance;
+    /** Schedules a one-shot timer outside the Angular zone, replacing any previous one. */
+    private schedule;
+    /** Cancels one timer if it is running. Safe to call for a timer that is not. */
+    private clearTimer;
+    /** Cancels every timer; used by `reset()` and on injector teardown. */
+    private clearAllTimers;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubLoadingBarService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<HubLoadingBarService>;
+}
+
+/**
+ * Default trickle curve: large steps early, then progressively smaller ones.
+ *
+ * The shape is what makes an invented number believable. Moving fast at the start
+ * matches the part of a page load that really is fast (the request goes out, the shell
+ * responds); slowing near the end matches the part nobody can predict, and leaves room
+ * for `complete()` to arrive without the bar having to jump backwards.
+ *
+ * Exported so a consumer can wrap it rather than rewrite it.
+ *
+ * @param progress - Current value, 0–100.
+ * @returns Amount to add on this tick.
+ */
+declare function hubLoadingBarTrickle(progress: number): number;
+/**
+ * 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_BAR_DEFAULT_CONFIG: HubLoadingBarConfig;
+/**
+ * Resolved defaults shared by `<hub-loading-bar>` and `HubLoadingBarService`.
+ *
+ * Declared with a root factory so the token is always injectable, even when the
+ * application never calls {@link provideHubLoadingBar}.
+ */
+declare const HUB_LOADING_BAR_CONFIG: InjectionToken<HubLoadingBarConfig>;
+/**
+ * Registers application-wide loading-bar defaults — the accent, the pacing, the
+ * translated label — so individual call sites stay bare.
+ *
+ * @param config - Values overriding {@link HUB_LOADING_BAR_DEFAULT_CONFIG}; omitted keys keep their default.
+ * @returns Environment providers for the application bootstrap.
+ */
+declare function provideHubLoadingBar(config?: Partial<HubLoadingBarConfig>): EnvironmentProviders;
+
+/**
+ * Marks a request as invisible to the loading bar.
+ *
+ * The escape hatch is not a nicety. A poll on a timer, a heartbeat, an autosave — any
+ * request the reader did not ask for — would otherwise hold the bar open forever, and a
+ * progress bar that never finishes is worse than none.
+ */
+declare const HUB_LOADING_BAR_SKIP: HttpContextToken<boolean>;
+/**
+ * Builds the `HttpContext` that hides one request from the loading bar.
+ *
+ * @param context - Existing context to extend; a fresh one by default.
+ * @returns The context, with the skip flag set.
+ *
+ * @example
+ * ```typescript
+ * this.http.get('/api/notifications', { context: withoutHubLoadingBar() });
+ * ```
+ */
+declare function withoutHubLoadingBar(context?: HttpContext): HttpContext;
+/**
+ * Holds the loading bar open for the lifetime of every HTTP request.
+ *
+ * The bar's reference counter is what makes this safe to combine with the router
+ * integration and with hand-written `start()` calls: six parallel requests are six
+ * callers, and the bar completes when the last of them does, not the first.
+ *
+ * `finalize` is the balancing point rather than a `tap` on success, because it also fires
+ * when the request errors and when the caller unsubscribes — a cancelled typeahead is the
+ * commonest way a naive interceptor strands the bar at 90%.
+ *
+ * Opt a request out with {@link withoutHubLoadingBar}.
+ *
+ * @example
+ * ```typescript
+ * provideHttpClient(withInterceptors([hubLoadingBarInterceptor]))
+ * ```
+ */
+declare const hubLoadingBarInterceptor: HttpInterceptorFn;
+
+/**
+ * Drives the loading bar from router navigation, which is the "page is loading" the bar
+ * is named after: it starts when a navigation begins and completes when it settles —
+ * including when it is cancelled by a guard or fails, because a bar left running after a
+ * rejected navigation is a bar that never goes away.
+ *
+ * Navigations are tracked with a flag rather than by pairing events one-to-one. The
+ * router's event sequence varies with configuration (a blocking initial navigation, a
+ * redirect, a skipped same-URL navigation), and the flag guarantees exactly one
+ * `start()` / `complete()` pair per navigation whatever order the events arrive in — a
+ * missed `NavigationStart` during bootstrap can no longer leave an unmatched `complete()`
+ * decrementing somebody else's count.
+ *
+ * Combine with {@link hubLoadingBarInterceptor} when routes fetch their own data: the
+ * navigation settles as soon as the component is created, so without the interceptor the
+ * bar finishes while the page is still empty.
+ *
+ * @returns Environment providers for the application bootstrap.
+ *
+ * @example
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideRouter(routes), provideHubLoadingBarRouter()]
+ * });
+ * ```
+ */
+declare function provideHubLoadingBarRouter(): EnvironmentProviders;
+
+export { HUB_LOADING_BAR_CONFIG, HUB_LOADING_BAR_DEFAULT_CONFIG, HUB_LOADING_BAR_SKIP, HUB_LOADING_CONFIG, HUB_LOADING_DEFAULT_CONFIG, HubLoadingBarComponent, HubLoadingBarService, HubLoadingComponent, HubLoadingService, hubLoadingBarInterceptor, hubLoadingBarTrickle, provideHubLoading, provideHubLoadingBar, provideHubLoadingBarRouter, withoutHubLoadingBar };
+export type { HubLoadingBarConfig, HubLoadingBarMode, HubLoadingBarPlacement, HubLoadingBarTrickle, HubLoadingConfig, HubLoadingImageAnimation, HubLoadingMode, HubLoadingOptions, HubLoadingSize, HubLoadingVariant };