@rdlabo/ionic-angular-kit 0.0.3 → 0.0.4

package/types/rdlabo-ionic-angular-kit.d.ts

@@ -0,0 +1,767 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders, OnInit } from '@angular/core';
+import { ModalOptions, ToastOptions } from '@ionic/angular/standalone';
+import { RouterStateSnapshot, UrlTree, CanActivateFn } from '@angular/router';
+import { Observable } from 'rxjs';
+import { HttpRequest, HttpResponse, HttpErrorResponse, HttpEvent, HttpInterceptorFn } from '@angular/common/http';
+import { ImpactStyle } from '@capacitor/haptics';
+
+/**
+ * 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');
+ * }
+ * ```
+ */
+declare class KitStorageService {
+    #private;
+    /**
+     * 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' });
+     * ```
+     */
+    set<T>(key: string, value: T): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    get<T>(key: string): Promise<T | 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
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Remove every key/value pair from the store.
+     *
+     * @returns a Promise that resolves once the store has been emptied
+     */
+    clear(): Promise<void>;
+    /**
+     * List every key currently present in the store.
+     *
+     * @returns an array of all stored keys
+     */
+    keys(): Promise<string[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitStorageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KitStorageService>;
+}
+
+/**
+ * User-visible button labels consumed by `KitOverlayController`.
+ *
+ * @remarks
+ * The kit deliberately ships no i18n strings of its own and has no hard dependency on
+ * `@angular/localize`. The consuming application always provides these labels: multilingual apps
+ * pass `$localize`-resolved strings, single-language apps pass plain literals.
+ */
+interface KitLabels {
+    /** Text for the "close" button used by alerts and toasts. */
+    readonly close: string;
+    /** Text for the "cancel" button used by confirmation alerts. */
+    readonly cancel: string;
+}
+/**
+ * Overlay configuration injected via `provideKitOverlay()`.
+ *
+ * @remarks
+ * All fields are required; the consuming application must supply a complete configuration.
+ */
+interface KitOverlayConfig {
+    /** Button labels used across the overlays presented by `KitOverlayController`. */
+    readonly labels: KitLabels;
+}
+/**
+ * Injection token carrying the {@link KitOverlayConfig} for `KitOverlayController`.
+ *
+ * @remarks
+ * Provide it through {@link provideKitOverlay} rather than registering it directly.
+ */
+declare const KIT_OVERLAY_CONFIG: InjectionToken<KitOverlayConfig>;
+/**
+ * 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` } }),
+ *   ],
+ * });
+ * ```
+ */
+declare const provideKitOverlay: (config: KitOverlayConfig) => EnvironmentProviders;
+
+/**
+ * Options for {@link KitOverlayController.presentModal}.
+ *
+ * @remarks
+ * Extends Ionic's `ModalOptions` but omits `component` and `componentProps`, which are passed as
+ * dedicated arguments instead.
+ */
+interface KitModalPresentOptions extends Omit<ModalOptions, 'component' | 'componentProps'> {
+    /**
+     * When `true`, expand the sheet to its maximum breakpoint while the native keyboard is shown.
+     *
+     * @remarks
+     * Only has an effect on native platforms; ignored on the web.
+     */
+    watchKeyboard?: boolean;
+}
+/**
+ * Options for {@link KitOverlayController.alertClose}.
+ */
+interface KitAlertCloseOptions {
+    /** Alert header text. */
+    header: string;
+    /** Alert body message. */
+    message: string;
+    /** Optional alert sub-header text shown beneath the header. */
+    subHeader?: string;
+}
+/**
+ * Options for {@link KitOverlayController.alertConfirm}.
+ *
+ * @remarks
+ * Extends {@link KitAlertCloseOptions} with the confirm-button text.
+ */
+interface KitAlertConfirmOptions extends KitAlertCloseOptions {
+    /**
+     * Text for the OK (confirm) button.
+     *
+     * @remarks
+     * Action-specific, so it is supplied by the caller rather than taken from the shared labels.
+     */
+    okText: string;
+}
+/**
+ * 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' });
+ *   }
+ * }
+ * ```
+ */
+declare class KitOverlayController {
+    #private;
+    /**
+     * 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 });
+     * ```
+     */
+    presentModal<O = unknown>(component: ModalOptions['component'], componentProps?: ModalOptions['componentProps'], options?: KitModalPresentOptions): Promise<O | undefined>;
+    /**
+     * 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' });
+     * ```
+     */
+    presentToast(options: ToastOptions): Promise<HTMLIonToastElement>;
+    /**
+     * 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.' });
+     * ```
+     */
+    alertClose(options: KitAlertCloseOptions): Promise<void>;
+    /**
+     * 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();
+     * }
+     * ```
+     */
+    alertConfirm(options: KitAlertConfirmOptions): Promise<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitOverlayController, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KitOverlayController>;
+}
+
+/**
+ * Content for {@link KitReloadAlertController.present}.
+ */
+interface KitReloadAlertOptions {
+    /** Alert header text. */
+    header: string;
+    /** Alert body message. */
+    message: string;
+    /**
+     * Text for the reload (confirm) button, e.g. "リフレッシュ".
+     *
+     * @remarks
+     * Action-specific, so it is supplied by the caller rather than taken from the shared labels.
+     * The cancel button uses the configured {@link KitLabels.cancel}.
+     */
+    okText: string;
+}
+/**
+ * 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();
+ * ```
+ */
+declare class KitReloadAlertController {
+    #private;
+    /**
+     * 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)
+     */
+    present(options: KitReloadAlertOptions): Promise<void>;
+    /**
+     * 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)
+     */
+    dismiss(): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitReloadAlertController, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KitReloadAlertController>;
+}
+
+/**
+ * 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>
+ * ```
+ */
+declare class KitAutofillDirective implements OnInit {
+    #private;
+    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(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitAutofillDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KitAutofillDirective, "[rdlaboAutofill]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Discriminated set of authentication states the guards react to.
+ *
+ * @remarks
+ * The application is responsible for emitting these values through {@link KitAuthConfig.authState}.
+ * An application that does not use a value (for example email confirmation) simply never emits it.
+ *
+ * - `user` — fully authenticated and verified.
+ * - `confirm` — awaiting email confirmation.
+ * - `required` — not authenticated.
+ * - `anonymous` — signed in anonymously; the user can still be guided toward full registration.
+ */
+type KitAuthState = 'user' | 'confirm' | 'required' | 'anonymous';
+/**
+ * Redirect targets (route paths) used by the guards when access is denied.
+ *
+ * @remarks
+ * Every field is required and must be provided per application, because the guards have no
+ * knowledge of the host application's route layout.
+ */
+interface KitAuthRedirects {
+    /** Used by {@link kitRequiredUnauthorizedGuard}: where to navigate when the user is already authenticated (`user`). */
+    readonly whenAuthorized: string;
+    /** Used by {@link kitRequiredUnauthorizedGuard}: where to navigate when the user is awaiting email confirmation (`confirm`). */
+    readonly whenConfirming: string;
+    /** Used by {@link kitRequireConfirmingGuard}: where to navigate when the state is not `confirm`. */
+    readonly whenNotConfirming: string;
+    /** Used by {@link kitRequireAuthorizedGuard}: where to navigate when the state is not `user` and the fallback is not allowed. */
+    readonly whenUnauthorized: string;
+}
+/**
+ * Configuration consumed by the authentication guards, injected through {@link provideKitAuth}.
+ *
+ * @remarks
+ * All members are required. The hooks let the host application plug its own auth service and
+ * navigation policy into the otherwise fixed guard control flow.
+ */
+interface KitAuthConfig {
+    /**
+     * Source of the current authentication state.
+     *
+     * @remarks
+     * Typically backed by the application's own auth service (for example `AuthService.isAuth()`).
+     *
+     * @returns A stream of {@link KitAuthState} values.
+     */
+    authState(): Observable<KitAuthState>;
+    /**
+     * Application-specific work that runs in {@link kitRequireAuthorizedGuard} after the state is confirmed to be `user`.
+     *
+     * @remarks
+     * Typical responsibilities include token login, permission checks, terms-of-service acceptance,
+     * or restoring a previously requested redirect.
+     *
+     * @param state - The router state snapshot of the route being activated.
+     * @returns `true` to allow activation, or a `UrlTree` to perform a custom redirect.
+     */
+    onAuthorized(state: RouterStateSnapshot): Promise<boolean | UrlTree>;
+    /**
+     * Fallback that runs in {@link kitRequireAuthorizedGuard} when the state is `required` (not authenticated).
+     *
+     * @remarks
+     * For example, attempt an anonymous sign-in and allow the route. Applications that do not need
+     * this should pass `async () => false` to fall through to the default redirect.
+     *
+     * @param state - The router state snapshot of the route being activated.
+     * @returns `true` to allow activation, a `UrlTree` for a custom redirect, or `false` to use the default redirect.
+     */
+    onUnauthenticated(state: RouterStateSnapshot): Promise<boolean | UrlTree>;
+    /** Redirect targets used by the guards. */
+    redirects: KitAuthRedirects;
+}
+/**
+ * Injection token that carries the {@link KitAuthConfig} to the authentication guards.
+ */
+declare const KIT_AUTH_CONFIG: InjectionToken<KitAuthConfig>;
+/**
+ * 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',
+ *     },
+ *   };
+ * });
+ * ```
+ */
+declare const provideKitAuth: (configFactory: () => KitAuthConfig) => EnvironmentProviders;
+/**
+ * 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] }];
+ * ```
+ */
+declare const kitRequiredUnauthorizedGuard: CanActivateFn;
+/**
+ * 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] }];
+ * ```
+ */
+declare const kitRequireConfirmingGuard: CanActivateFn;
+/**
+ * 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] }];
+ * ```
+ */
+declare const kitRequireAuthorizedGuard: CanActivateFn;
+
+/**
+ * Configuration that customizes the behavior of {@link kitAuthInterceptor}, injected through {@link provideKitHttp}.
+ *
+ * @remarks
+ * The interceptor fixes the retry policy (up to 2 retries with a linearly increasing backoff, plus immediate
+ * throw on `401` and on every {@link NON_RETRYABLE_STATUSES | non-retryable status}) and the overall
+ * control flow. Only the hooks below are application-specific.
+ *
+ * Only {@link KitHttpConfig.getAuthHeaders} is required — it has no safe default. Every other hook is
+ * optional and defaults to a no-op (or `{}` / `false` / `null` as appropriate), so an app configures
+ * only the behavior that actually differs from the canonical baseline.
+ */
+interface KitHttpConfig {
+    /**
+     * Produce authentication and metadata headers for the outgoing request.
+     *
+     * @param request - The outgoing request about to be sent.
+     * @returns A map of header names to values, resolved asynchronously.
+     */
+    getAuthHeaders(request: HttpRequest<unknown>): Promise<Record<string, string>>;
+    /**
+     * Produce additional headers for the outgoing request.
+     *
+     * @remarks
+     * Optional; defaults to adding no extra headers.
+     *
+     * @param request - The outgoing request about to be sent.
+     * @returns A map of header names to values; return `{}` when none are needed.
+     */
+    buildExtraHeaders?(request: HttpRequest<unknown>): Record<string, string>;
+    /**
+     * Called for every successful response that completed an actual network round trip.
+     *
+     * @remarks
+     * Responses synthesized by {@link KitHttpConfig.offlineFallback} are produced after `catchError`
+     * and therefore never reach this hook, so it observes genuine successes only. A typical use is to
+     * reset an "offline" flag once connectivity is restored. Optional; defaults to a no-op.
+     *
+     * @param event - The successful `HttpResponse`.
+     */
+    onResponse?(event: HttpResponse<unknown>): void;
+    /**
+     * Decide whether to pass the request straight through, skipping auth, retry, and error handling.
+     *
+     * @remarks
+     * Useful for external URLs such as S3 or a CDN. Optional; defaults to `false` (never bypass).
+     *
+     * @param request - The outgoing request.
+     * @returns `true` to bypass the interceptor pipeline.
+     */
+    bypass?(request: HttpRequest<unknown>): boolean;
+    /**
+     * Provide an offline short-circuit when a request fails.
+     *
+     * @remarks
+     * Returning a non-null observable replaces the error with that response (for example a queued
+     * offline result). Optional; defaults to `null` (no fallback, normal error handling proceeds).
+     *
+     * @param request - The request that failed (after headers were applied).
+     * @param error - The error response that triggered the fallback.
+     * @returns A replacement event stream, or `null` for no fallback.
+     */
+    offlineFallback?(request: HttpRequest<unknown>, error: HttpErrorResponse): Observable<HttpEvent<unknown>> | null;
+    /**
+     * Side effect to run on a `401` response (for example an expired token).
+     *
+     * @remarks
+     * Optional; defaults to a no-op.
+     *
+     * @param request - The request that received the `401`.
+     */
+    onUnauthorized?(request: HttpRequest<unknown>): void;
+    /**
+     * Side effect to run on a `403` response (a permission error).
+     *
+     * @remarks
+     * Optional; defaults to a no-op.
+     *
+     * @param request - The request that received the `403`.
+     */
+    onForbidden?(request: HttpRequest<unknown>): void;
+    /**
+     * UX hook for network-originated errors while the device is connected.
+     *
+     * @remarks
+     * Optional; defaults to a no-op. The kit ships {@link KitReloadAlertController} as the fleet's
+     * canonical implementation of this hook (with auto-dismiss on reconnect via `onResponse`).
+     *
+     * @param status - The HTTP status code, or a string descriptor for non-HTTP failures.
+     * @returns Optionally a promise to await before continuing.
+     */
+    onNetworkError?(status: number | string): Promise<void> | void;
+    /**
+     * UX hook for `400` / `500` responses that carry a server-provided message.
+     *
+     * @remarks
+     * Optional; defaults to a no-op.
+     *
+     * @param message - The message extracted from the error body.
+     */
+    onServerError?(message: string): void;
+}
+/**
+ * Injection token that carries the {@link KitHttpConfig} to {@link kitAuthInterceptor}.
+ */
+declare const KIT_HTTP_CONFIG: InjectionToken<KitHttpConfig>;
+/**
+ * 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(),
+ *       };
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const provideKitHttp: (configFactory: () => KitHttpConfig) => EnvironmentProviders;
+/**
+ * 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]));
+ * ```
+ */
+declare const kitAuthInterceptor: HttpInterceptorFn;
+
+/**
+ * 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);
+ * ```
+ */
+declare const kitImpact: (style?: ImpactStyle) => Promise<void>;
+
+/**
+ * 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' }]
+ * ```
+ */
+declare const arrayConcatById: <T>(arrayOld: T[], arrayNew: T[], key: keyof T, order?: "ASC" | "DESC") => T[];
+
+export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KitAutofillDirective, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, kitAuthInterceptor, kitImpact, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, provideKitAuth, provideKitHttp, provideKitOverlay };
+export type { KitAlertCloseOptions, KitAlertConfirmOptions, KitAuthConfig, KitAuthRedirects, KitAuthState, KitHttpConfig, KitLabels, KitModalPresentOptions, KitOverlayConfig, KitReloadAlertOptions };