@rdlabo/ionic-angular-kit 0.0.3 → 0.0.4

package/fesm2022/rdlabo-ionic-angular-kit.mjs

@@ -0,0 +1,797 @@
+import * as i0 from '@angular/core';
+import { inject, Injectable, InjectionToken, makeEnvironmentProviders, ElementRef, Directive } from '@angular/core';
+import { Storage } from '@ionic/storage-angular';
+import { ModalController, ToastController, AlertController, NavController } from '@ionic/angular/standalone';
+import { Capacitor } from '@capacitor/core';
+import { Keyboard } from '@capacitor/keyboard';
+import { ImpactStyle, Haptics } from '@capacitor/haptics';
+import { Router } from '@angular/router';
+import { map, mergeMap, tap, catchError } from 'rxjs/operators';
+import { HttpResponse } from '@angular/common/http';
+import { Network } from '@capacitor/network';
+import { from, retry, throwError, timer } from 'rxjs';
+
+/**
+ * Thin, typed wrapper around `@ionic/storage-angular`.
+ *
+ * Starts `create()` exactly once and stores the resulting ready Promise. Every operation awaits
+ * that Promise before touching the underlying store, so calls made before initialization completes
+ * are queued rather than dropped.
+ *
+ * @remarks
+ * A naive wrapper that reads the store synchronously would silently no-op (or throw) when invoked
+ * before `create()` resolves, losing early writes. Awaiting the one-time ready Promise on every
+ * operation removes that race without forcing callers to coordinate initialization themselves.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly storage: KitStorageService) {}
+ *
+ * async ngOnInit(): Promise<void> {
+ *   await this.storage.set('token', 'abc123');
+ *   const token = await this.storage.get<string>('token');
+ * }
+ * ```
+ */
+class KitStorageService {
+    /** One-time `create()` ready Promise; awaited before every operation so early calls are not lost. */
+    #ready = inject(Storage).create();
+    /**
+     * Persist a value under the given key.
+     *
+     * @typeParam T - type of the value being stored
+     * @param key - key to store the value under
+     * @param value - value to persist; overwrites any existing value for the key
+     * @returns a Promise that resolves once the value has been written
+     * @example
+     * ```ts
+     * await storage.set('user', { id: 1, name: 'Ada' });
+     * ```
+     */
+    async set(key, value) {
+        await (await this.#ready).set(key, value);
+    }
+    /**
+     * Read the value stored under the given key.
+     *
+     * @typeParam T - expected type of the stored value
+     * @param key - key to read
+     * @returns the stored value, or `null` when the key is absent
+     * @example
+     * ```ts
+     * const user = await storage.get<{ id: number }>('user');
+     * ```
+     */
+    async get(key) {
+        return (await (await this.#ready).get(key)) ?? null;
+    }
+    /**
+     * Remove the value stored under the given key.
+     *
+     * @param key - key to remove; a no-op when the key is absent
+     * @returns a Promise that resolves once the key has been removed
+     */
+    async remove(key) {
+        await (await this.#ready).remove(key);
+    }
+    /**
+     * Remove every key/value pair from the store.
+     *
+     * @returns a Promise that resolves once the store has been emptied
+     */
+    async clear() {
+        await (await this.#ready).clear();
+    }
+    /**
+     * List every key currently present in the store.
+     *
+     * @returns an array of all stored keys
+     */
+    async keys() {
+        return (await this.#ready).keys();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitStorageService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitStorageService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitStorageService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+/**
+ * Injection token carrying the {@link KitOverlayConfig} for `KitOverlayController`.
+ *
+ * @remarks
+ * Provide it through {@link provideKitOverlay} rather than registering it directly.
+ */
+const KIT_OVERLAY_CONFIG = new InjectionToken('@rdlabo/ionic-angular-kit:overlay');
+/**
+ * Wire `KitOverlayController` into the application by providing its button labels.
+ *
+ * @param config - overlay configuration, including the button labels to inject
+ * @returns environment providers to add to the application's provider list
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitOverlay({ labels: { close: $localize`Close`, cancel: $localize`Cancel` } }),
+ *   ],
+ * });
+ * ```
+ */
+const provideKitOverlay = (config) => makeEnvironmentProviders([{ provide: KIT_OVERLAY_CONFIG, useValue: config }]);
+
+/**
+ * Trigger native haptic impact feedback.
+ *
+ * Delegates to `@capacitor/haptics` `Haptics.impact()` when running on a native platform. On the
+ * web (or any non-native platform) it is a no-op and resolves without doing anything.
+ *
+ * @remarks
+ * This haptic side effect was previously bundled implicitly into toast/modal presentation. It has
+ * been decoupled into this explicit function so callers opt in to the feedback deliberately, rather
+ * than receiving it as a hidden side effect of presenting UI.
+ *
+ * @param style - The impact intensity to play. Defaults to {@link ImpactStyle.Light}.
+ * @returns A promise that resolves once the feedback has been requested (immediately on the web).
+ * @example
+ * ```ts
+ * import { ImpactStyle } from '@capacitor/haptics';
+ *
+ * // Light tap (default)
+ * await kitImpact();
+ *
+ * // Stronger feedback, e.g. on a confirming action
+ * await kitImpact(ImpactStyle.Heavy);
+ * ```
+ */
+const kitImpact = async (style = ImpactStyle.Light) => {
+    if (Capacitor.isNativePlatform()) {
+        await Haptics.impact({ style });
+    }
+};
+
+/**
+ * Attach a native keyboard listener that grows the modal to its maximum breakpoint when the
+ * keyboard appears.
+ *
+ * @param modal - the presented modal element to resize
+ * @returns a listener handle; on non-native platforms a no-op handle whose `remove()` does nothing
+ * @internal
+ */
+const watchModalKeyboard = async (modal) => {
+    if (!Capacitor.isNativePlatform()) {
+        return { remove: async () => undefined };
+    }
+    return Keyboard.addListener('keyboardDidShow', () => modal.setCurrentBreakpoint(1));
+};
+/**
+ * Ergonomic wrapper that consolidates Ionic's overlay controllers (Modal / Toast / Alert).
+ *
+ * @remarks
+ * Folds the repetitive create → present → onDidDismiss sequence into single calls and returns the
+ * relevant result directly. It holds no application-specific policy such as navigation; compose
+ * those concerns on the consuming side.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly overlay: KitOverlayController) {}
+ *
+ * async edit(): Promise<void> {
+ *   const result = await this.overlay.presentModal<EditResult>(EditPage, { id: 1 });
+ *   if (result) {
+ *     await this.overlay.presentToast({ message: 'Saved' });
+ *   }
+ * }
+ * ```
+ */
+class KitOverlayController {
+    #modalCtrl = inject(ModalController);
+    #toastCtrl = inject(ToastController);
+    #alertCtrl = inject(AlertController);
+    #labels = inject(KIT_OVERLAY_CONFIG).labels;
+    /**
+     * Present a modal and resolve with the data passed to its dismissal.
+     *
+     * @typeParam O - type of the data returned when the modal is dismissed
+     * @param component - the component to render inside the modal
+     * @param componentProps - props to pass to the modal component
+     * @param options - additional modal options, including {@link KitModalPresentOptions.watchKeyboard}
+     * @returns the dismiss data, or `undefined` when the modal is dismissed without data
+     * @example
+     * ```ts
+     * const data = await overlay.presentModal<{ saved: boolean }>(EditPage, { id: 1 }, { watchKeyboard: true });
+     * ```
+     */
+    async presentModal(component, componentProps, options = {}) {
+        const { watchKeyboard, ...modalOptions } = options;
+        const modal = await this.#modalCtrl.create({ component, componentProps, ...modalOptions });
+        await modal.present();
+        const handle = watchKeyboard ? await watchModalKeyboard(modal) : null;
+        const { data } = await modal.onDidDismiss();
+        await handle?.remove();
+        return data;
+    }
+    /**
+     * Present a toast using kit defaults that the caller may override.
+     *
+     * @remarks
+     * Defaults to a top position, a 2000ms duration, a vertical swipe gesture, and a close button
+     * from the configured labels; any of these can be overridden via `options`. Presenting a toast
+     * also triggers light native haptic feedback as an intentional kit UX choice.
+     *
+     * @param options - Ionic toast options that override the kit defaults
+     * @returns the presented toast element
+     * @example
+     * ```ts
+     * await overlay.presentToast({ message: 'Copied to clipboard' });
+     * ```
+     */
+    async presentToast(options) {
+        void kitImpact();
+        const toast = await this.#toastCtrl.create({
+            position: 'top',
+            duration: 2000,
+            buttons: [this.#labels.close],
+            swipeGesture: 'vertical',
+            ...options,
+        });
+        await toast.present();
+        return toast;
+    }
+    /**
+     * Present a notification alert with a single "close" button and wait for it to be dismissed.
+     *
+     * @param options - alert content (header, message, optional sub-header)
+     * @returns a Promise that resolves once the alert has been dismissed
+     * @example
+     * ```ts
+     * await overlay.alertClose({ header: 'Done', message: 'Your changes were saved.' });
+     * ```
+     */
+    async alertClose(options) {
+        const alert = await this.#alertCtrl.create({
+            header: options.header,
+            subHeader: options.subHeader,
+            message: options.message,
+            buttons: [this.#labels.close],
+        });
+        await alert.present();
+        await alert.onWillDismiss();
+    }
+    /**
+     * Present a confirmation alert with cancel and OK buttons.
+     *
+     * @param options - alert content plus the OK button text via {@link KitAlertConfirmOptions.okText}
+     * @returns `true` when the user presses OK, `false` otherwise (cancel or backdrop dismissal)
+     * @example
+     * ```ts
+     * const ok = await overlay.alertConfirm({
+     *   header: 'Delete item?',
+     *   message: 'This cannot be undone.',
+     *   okText: 'Delete',
+     * });
+     * if (ok) {
+     *   await remove();
+     * }
+     * ```
+     */
+    async alertConfirm(options) {
+        const alert = await this.#alertCtrl.create({
+            header: options.header,
+            subHeader: options.subHeader,
+            message: options.message,
+            buttons: [
+                { text: this.#labels.cancel, role: 'cancel' },
+                { text: options.okText, role: 'confirm' },
+            ],
+        });
+        await alert.present();
+        const { role } = await alert.onWillDismiss();
+        return role === 'confirm';
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitOverlayController, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitOverlayController, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitOverlayController, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+/**
+ * The fleet's canonical "network error → offer to reload" alert, as a stateful controller.
+ *
+ * @remarks
+ * Consolidates the good-UX variant that had drifted across the fleet into one behavior:
+ *
+ * - **De-dup** — never stacks; a second {@link present} while an alert is already shown is a no-op.
+ * - **Backdrop lock** — `backdropDismiss: false`, so a critical network error can't be dismissed by
+ *   an accidental backdrop tap; the user consciously chooses cancel or reload.
+ * - **Auto-dismiss on reconnect** — the presented alert is tracked, so {@link dismiss} (called from a
+ *   later successful response) clears a now-stale error alert instead of leaving it on screen.
+ * - **Reload on confirm** — the confirm button calls `location.reload()`.
+ *
+ * All user-facing text is supplied by the caller so the kit stays free of any hardcoded i18n; the
+ * cancel button reuses {@link KitOverlayConfig.labels}. Because it performs navigation
+ * (`location.reload()`) and holds state, it is a dedicated controller rather than part of
+ * {@link KitOverlayController}, which stays free of navigation policy.
+ *
+ * @example
+ * ```ts
+ * // In an HTTP interceptor:
+ * const reload = inject(KitReloadAlertController);
+ * // ...on a network-class error while connected:
+ * await reload.present({ header: 'ネットワークエラー', message: `…（${status}）`, okText: 'リフレッシュ' });
+ * // ...on any later successful response:
+ * await reload.dismiss();
+ * ```
+ */
+class KitReloadAlertController {
+    #alertCtrl = inject(AlertController);
+    #labels = inject(KIT_OVERLAY_CONFIG).labels;
+    #alert = null;
+    /**
+     * Present the reload alert, unless one is already on screen.
+     *
+     * @param options - alert content plus the reload-button text
+     * @returns a Promise that resolves once the alert has been presented (or immediately if suppressed)
+     */
+    async present(options) {
+        // この controller 経由でも直書き ion-alert でも、多重表示しない。
+        if (this.#alert || document.querySelector('ion-alert')) {
+            return;
+        }
+        const alert = await this.#alertCtrl.create({
+            header: options.header,
+            message: options.message,
+            backdropDismiss: false,
+            buttons: [
+                { text: this.#labels.cancel, role: 'cancel' },
+                {
+                    text: options.okText,
+                    handler: () => {
+                        location.reload();
+                    },
+                },
+            ],
+        });
+        this.#alert = alert;
+        void alert.onDidDismiss().then(() => {
+            // 別の present で置き換わっていない限り、追跡を解除する。
+            if (this.#alert === alert) {
+                this.#alert = null;
+            }
+        });
+        await alert.present();
+    }
+    /**
+     * Dismiss the tracked reload alert if one is showing.
+     *
+     * @remarks
+     * Typically called from a later successful response so a stale "network error" alert clears once
+     * connectivity is restored. A no-op when nothing is showing.
+     *
+     * @returns a Promise that resolves once the alert has been dismissed (or immediately if none)
+     */
+    async dismiss() {
+        const alert = this.#alert;
+        this.#alert = null;
+        await alert?.dismiss();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitReloadAlertController, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitReloadAlertController, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitReloadAlertController, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+/**
+ * Work around iOS `ion-input` autofill values not propagating to the Angular form model.
+ *
+ * On iOS, when the browser autofills an `ion-input` (for example a saved password), the value
+ * is written to the underlying native `<input>` element but the corresponding `change` event is
+ * not forwarded to the host `ion-input`, so the Angular form control (and `ngModel`) never sees
+ * the autofilled value. This directive listens for the first `change` event on the inner input
+ * element and mirrors its value back onto the host element, restoring two-way binding.
+ *
+ * Apply it to any `ion-input` that participates in a form and may be autofilled by attaching the
+ * `rdlaboAutofill` attribute.
+ *
+ * @remarks
+ * The directive is a no-op on every platform other than iOS, where the value already propagates
+ * correctly. A short timeout is used because `ion-input` creates its inner `<input>` element
+ * asynchronously after the host element is initialized.
+ *
+ * @example
+ * ```html
+ * <ion-input rdlaboAutofill type="password" [(ngModel)]="password"></ion-input>
+ * ```
+ */
+class KitAutofillDirective {
+    #el = inject(ElementRef);
+    constructor() { }
+    /**
+     * Register the iOS autofill workaround once the directive is initialized.
+     *
+     * Returns immediately on non-iOS platforms. On iOS, after a short delay it attaches a one-shot,
+     * passive `change` listener to the inner `<input>` element that `ion-input` renders, copying the
+     * autofilled value back onto the host element so the Angular form model stays in sync. Any error
+     * while locating the inner input (for example if the element is not yet present) is swallowed.
+     *
+     * @returns Nothing.
+     */
+    ngOnInit() {
+        if (Capacitor.getPlatform() !== 'ios') {
+            return;
+        }
+        setTimeout(() => {
+            try {
+                this.#el.nativeElement.children[0].addEventListener('change', (e) => {
+                    this.#el.nativeElement.value = e.target.value;
+                }, {
+                    capture: false,
+                    once: true,
+                    passive: true,
+                });
+            }
+            catch {
+                /* empty */
+            }
+        }, 100); // Need some time for the ion-input to create the input element
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitAutofillDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.17", type: KitAutofillDirective, isStandalone: true, selector: "[rdlaboAutofill]", ngImport: i0 }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitAutofillDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[rdlaboAutofill]',
+                    standalone: true,
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Injection token that carries the {@link KitAuthConfig} to the authentication guards.
+ */
+const KIT_AUTH_CONFIG = new InjectionToken('@rdlabo/ionic-angular-kit:auth');
+/**
+ * Wire the authentication guard configuration into the application's dependency injection.
+ *
+ * @remarks
+ * The factory runs inside an injection context, so it may call `inject()` (for example
+ * `inject(AuthService)`) to build the configuration.
+ *
+ * @param configFactory - Factory that returns the {@link KitAuthConfig} for the application.
+ * @returns Environment providers to add to the application bootstrap.
+ *
+ * @example
+ * ```ts
+ * provideKitAuth(() => {
+ *   const auth = inject(AuthService);
+ *   return {
+ *     authState: () => auth.isAuth(),
+ *     onAuthorized: async () => true,
+ *     onUnauthenticated: async () => false,
+ *     redirects: {
+ *       whenAuthorized: '/',
+ *       whenConfirming: '/auth/confirm',
+ *       whenNotConfirming: '/auth/signin',
+ *       whenUnauthorized: 'auth',
+ *     },
+ *   };
+ * });
+ * ```
+ */
+const provideKitAuth = (configFactory) => makeEnvironmentProviders([{ provide: KIT_AUTH_CONFIG, useFactory: configFactory }]);
+/**
+ * Guard that requires the user to be unauthenticated (for example sign-in or sign-up pages).
+ *
+ * @remarks
+ * Allows the `required` and `anonymous` states (an anonymous user is permitted to proceed to a
+ * registration page). An authenticated user (`user`) is sent to `whenAuthorized`, and a user
+ * awaiting confirmation (`confirm`) is sent to `whenConfirming`.
+ *
+ * @returns A stream emitting `true` to allow activation, or `false` after triggering a redirect.
+ *
+ * @example
+ * ```ts
+ * const routes: Routes = [{ path: 'signin', component: SigninPage, canActivate: [kitRequiredUnauthorizedGuard] }];
+ * ```
+ */
+const kitRequiredUnauthorizedGuard = () => {
+    const { authState, redirects } = inject(KIT_AUTH_CONFIG);
+    const router = inject(Router);
+    const navCtrl = inject(NavController);
+    return authState().pipe(map((data) => {
+        if (data === 'user') {
+            navCtrl.setDirection('root');
+            router.navigate([redirects.whenAuthorized]);
+            return false;
+        }
+        else if (data === 'confirm') {
+            router.navigate([redirects.whenConfirming]);
+            return false;
+        }
+        // 'required' | 'anonymous'
+        return true;
+    }));
+};
+/**
+ * Guard that requires the user to be awaiting email confirmation (`confirm`).
+ *
+ * @remarks
+ * Any other state triggers a redirect: an `anonymous` user is sent to the authenticated area
+ * (`whenAuthorized`), and every remaining state is sent to `whenNotConfirming`.
+ *
+ * @returns A stream emitting `true` to allow activation, or `false` after triggering a redirect.
+ *
+ * @example
+ * ```ts
+ * const routes: Routes = [{ path: 'confirm', component: ConfirmPage, canActivate: [kitRequireConfirmingGuard] }];
+ * ```
+ */
+const kitRequireConfirmingGuard = () => {
+    const { authState, redirects } = inject(KIT_AUTH_CONFIG);
+    const router = inject(Router);
+    const navCtrl = inject(NavController);
+    return authState().pipe(map((data) => {
+        if (data === 'confirm') {
+            return true;
+        }
+        navCtrl.setDirection('root');
+        router.navigate([data === 'anonymous' ? redirects.whenAuthorized : redirects.whenNotConfirming]);
+        return false;
+    }));
+};
+/**
+ * Guard that requires the user to be fully authenticated (`user`).
+ *
+ * @remarks
+ * - `user` — runs {@link KitAuthConfig.onAuthorized} (token login, permission checks, and so on).
+ * - `anonymous` — allowed as-is, for applications that permit anonymous browsing.
+ * - `required` / `confirm` — runs {@link KitAuthConfig.onUnauthenticated}; if it resolves to `false`,
+ *   the user is redirected to `whenUnauthorized`.
+ *
+ * @param _route - The activated route snapshot (unused).
+ * @param state - The router state snapshot, forwarded to the configuration hooks.
+ * @returns A stream emitting the activation result: `true`, a `UrlTree`, or `false` after a redirect.
+ *
+ * @example
+ * ```ts
+ * const routes: Routes = [{ path: 'home', component: HomePage, canActivate: [kitRequireAuthorizedGuard] }];
+ * ```
+ */
+const kitRequireAuthorizedGuard = (_route, state) => {
+    const { authState, onAuthorized, onUnauthenticated, redirects } = inject(KIT_AUTH_CONFIG);
+    const router = inject(Router);
+    const navCtrl = inject(NavController);
+    return authState().pipe(mergeMap(async (data) => {
+        if (data === 'user') {
+            return onAuthorized(state);
+        }
+        if (data === 'anonymous') {
+            return true;
+        }
+        const fallback = await onUnauthenticated(state);
+        if (fallback !== false) {
+            return fallback;
+        }
+        navCtrl.setDirection('root');
+        router.navigate([redirects.whenUnauthorized]);
+        return false;
+    }));
+};
+
+/**
+ * HTTP status codes that must never be retried. `401` is handled separately and thrown immediately.
+ *
+ * @internal
+ */
+const NON_RETRYABLE_STATUSES = [400, 403, 404, 418, 500, 502];
+/**
+ * Injection token that carries the {@link KitHttpConfig} to {@link kitAuthInterceptor}.
+ */
+const KIT_HTTP_CONFIG = new InjectionToken('@rdlabo/ionic-angular-kit:http');
+/**
+ * Wire the {@link kitAuthInterceptor} configuration into the application's dependency injection.
+ *
+ * @remarks
+ * Register the interceptor itself separately via `provideHttpClient(withInterceptors([kitAuthInterceptor]))`.
+ * The factory runs inside an injection context, so it may call `inject()`.
+ *
+ * @param configFactory - Factory that returns the {@link KitHttpConfig} for the application.
+ * @returns Environment providers to add to the application bootstrap.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideHttpClient(withInterceptors([kitAuthInterceptor])),
+ *     provideKitHttp(() => {
+ *       const auth = inject(AuthService);
+ *       const reload = inject(KitReloadAlertController);
+ *       return {
+ *         // Only getAuthHeaders is required; every other hook is optional and defaults to a no-op.
+ *         getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
+ *         onUnauthorized: () => auth.signOut(),
+ *         onNetworkError: (status) =>
+ *           reload.present({ header: 'Network error', message: `Reload? (${status})`, okText: 'Reload' }),
+ *         onResponse: () => void reload.dismiss(),
+ *       };
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+const provideKitHttp = (configFactory) => makeEnvironmentProviders([{ provide: KIT_HTTP_CONFIG, useFactory: configFactory }]);
+/**
+ * Canonical functional HTTP interceptor that applies authentication, retries, and error handling.
+ *
+ * @remarks
+ * Behavior, driven by the injected {@link KitHttpConfig}:
+ *
+ * 1. Requests for which `bypass` returns `true` are forwarded untouched.
+ * 2. Otherwise the headers from `getAuthHeaders` and `buildExtraHeaders` are merged onto a cloned request.
+ * 3. Failed requests are retried up to 2 times with a linearly increasing backoff of `500ms * (retryCount + 5)`,
+ *    except that `401` and any {@link NON_RETRYABLE_STATUSES | non-retryable status}
+ *    (`400`, `403`, `404`, `418`, `500`, `502`) are thrown immediately without retrying.
+ * 4. On error, `offlineFallback` is consulted first; otherwise `401` calls `onUnauthorized`, `403`
+ *    calls `onForbidden`, network-class failures (anything other than `400`/`500`) call
+ *    `onNetworkError` when the device is connected, and `400`/`500` responses carrying a body
+ *    message call `onServerError`.
+ *
+ * @param request - The outgoing request.
+ * @param next - The next handler in the interceptor chain.
+ * @returns A stream of HTTP events for the (possibly modified, retried, or replaced) request.
+ *
+ * @example
+ * ```ts
+ * provideHttpClient(withInterceptors([kitAuthInterceptor]));
+ * ```
+ */
+const kitAuthInterceptor = (request, next) => {
+    const config = inject(KIT_HTTP_CONFIG);
+    if (config.bypass?.(request)) {
+        return next(request);
+    }
+    return from(config.getAuthHeaders(request)).pipe(mergeMap((authHeaders) => {
+        const req = request.clone({ setHeaders: { ...authHeaders, ...config.buildExtraHeaders?.(request) } });
+        return next(req).pipe(retry({
+            count: 2,
+            delay: (e, retryCount) => {
+                if (e.status === 401) {
+                    return throwError(() => e);
+                }
+                if (NON_RETRYABLE_STATUSES.includes(e.status)) {
+                    return throwError(() => e);
+                }
+                return timer((retryCount + 5) * 500);
+            },
+        }), tap((event) => {
+            if (event instanceof HttpResponse) {
+                config.onResponse?.(event);
+            }
+        }), catchError((e) => {
+            const fallback = config.offlineFallback?.(req, e);
+            if (fallback) {
+                return fallback;
+            }
+            if (e.status === 401) {
+                config.onUnauthorized?.(req);
+            }
+            else if (e.status === 403) {
+                config.onForbidden?.(req);
+            }
+            else if (![400, 500].includes(e.status)) {
+                void Network.getStatus().then((status) => {
+                    if (status.connected) {
+                        config.onNetworkError?.(e.status);
+                    }
+                });
+            }
+            else if (e.error?.message) {
+                config.onServerError?.(e.error.message);
+            }
+            return throwError(() => e);
+        }));
+    }));
+};
+
+/**
+ * Merge a newly fetched page of items into an existing list by id, keeping the result sorted.
+ *
+ * Items are merged by the numeric `key` field. On a duplicate `key` the item from `arrayNew` wins
+ * and replaces the one in `arrayOld`. Old items whose `key` falls *inside* the window spanned by
+ * `arrayNew` (between its first and last `key`) are dropped, since the freshly fetched page is the
+ * authoritative copy of that window; old items *outside* the window are kept. The merged items are
+ * finally sorted by `key`, ascending or descending according to `order`.
+ *
+ * The algorithm is:
+ * 1. If both inputs are empty, return an empty array.
+ * 2. Read the first (`lead`) and last (`last`) `key` values of `arrayNew` as the bounds of the
+ *    page's window. Keep the old items whose `key` lies *outside* that window (at or beyond the
+ *    extremes) and drop those strictly inside it, handling both a high-to-low page (`lead > last`)
+ *    and a low-to-high page (`lead < last`). A single-value page (`lead === last`) keeps all old items.
+ * 3. Remove old items whose `key` already exists in `arrayNew` (new wins on duplicates).
+ * 4. Concatenate `arrayNew` with the surviving old items and sort by `key` in the requested
+ *    direction.
+ *
+ * @remarks
+ * Designed for infinite-scroll / paginated list merging, where each fetched page may overlap the
+ * previously held items and the server returns a contiguous, ordered window of records. The `key`
+ * field is treated as a number for range comparison and sorting.
+ *
+ * @typeParam T - Element type of both arrays. Its `key` property must be a numeric value.
+ * @param arrayOld - The previously accumulated list. May be empty or nullish-safe (empty when falsy).
+ * @param arrayNew - The newly fetched page of items; its `key` range defines the window that its own
+ *   items replace, and its items take precedence on duplicates.
+ * @param key - The property of `T` used as the unique, numeric id for matching, range filtering, and sorting.
+ * @param order - Sort direction by `key`: `'ASC'` for ascending or `'DESC'` for descending. Defaults to `'DESC'`.
+ * @returns A new array containing `arrayNew` merged with the out-of-window, non-duplicate old items, sorted by `key`.
+ * @example
+ * ```ts
+ * interface Post {
+ *   id: number;
+ *   title: string;
+ * }
+ *
+ * const loaded: Post[] = [
+ *   { id: 30, title: 'c' },
+ *   { id: 20, title: 'b' },
+ *   { id: 10, title: 'a' },
+ * ];
+ * const nextPage: Post[] = [
+ *   { id: 20, title: 'b (updated)' },
+ *   { id: 15, title: 'a.5' },
+ * ];
+ *
+ * // Descending merge: id 30 lies above the new page's [15, 20] window so it is kept; id 20 is
+ * // inside the window and is replaced by the new value; id 10 lies below the window and is kept.
+ * const merged = arrayConcatById(loaded, nextPage, 'id', 'DESC');
+ * // => [{ id: 30, title: 'c' }, { id: 20, title: 'b (updated)' }, { id: 15, title: 'a.5' }, { id: 10, title: 'a' }]
+ * ```
+ */
+const arrayConcatById = (arrayOld, arrayNew, key, order = 'DESC') => {
+    if (!arrayNew.length && !arrayOld.length) {
+        return [];
+    }
+    const lead = arrayNew[0][key];
+    const last = arrayNew[arrayNew.length - 1][key];
+    const filteredOld = (arrayOld || []).filter((vol) => {
+        const value = vol[key];
+        return (lead > last && (value >= lead || value <= last)) || (lead < last && (value <= lead || value >= last)) || lead === last;
+    });
+    const oldData = filteredOld.filter((vol) => !arrayNew.some((element) => element[key] === vol[key]));
+    const data = arrayNew.concat(oldData);
+    const direction = order === 'ASC' ? 1 : -1;
+    return data.sort((a, b) => {
+        const x = a[key];
+        const y = b[key];
+        if (x > y) {
+            return direction;
+        }
+        if (x < y) {
+            return direction * -1;
+        }
+        return 0;
+    });
+};
+
+/*
+ * Public API Surface of @rdlabo/ionic-angular-kit
+ */
+// Storage: typed wrapper around the platform key/value store.
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KitAutofillDirective, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, kitAuthInterceptor, kitImpact, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, provideKitAuth, provideKitHttp, provideKitOverlay };
+//# sourceMappingURL=rdlabo-ionic-angular-kit.mjs.map