@rdlabo/ionic-angular-kit 0.0.15 → 0.0.17

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

@@ -1,10 +1,11 @@
 import * as i0 from '@angular/core';
-import { inject, Injectable, InjectionToken, makeEnvironmentProviders, ElementRef, Directive } from '@angular/core';
+import { inject, Injectable, InjectionToken, makeEnvironmentProviders, ElementRef, Injector, input, computed, HostListener, Directive } from '@angular/core';
 import { Storage } from '@ionic/storage-angular';
 import { ModalController, PopoverController, ToastController, AlertController, LoadingController, NavController } from '@ionic/angular/standalone';
 import { Capacitor } from '@capacitor/core';
 import { Keyboard } from '@capacitor/keyboard';
 import { ImpactStyle, Haptics } from '@capacitor/haptics';
+import { FORM_FIELD } from '@angular/forms/signals';
 import { Router } from '@angular/router';
 import { map, mergeMap, catchError, timeout, tap } from 'rxjs/operators';
 import { HttpErrorResponse, HttpResponse } from '@angular/common/http';
@@ -100,6 +101,62 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImpo
                 }]
         }] });
 
+/**
+ * Remember the email a user last entered on the sign-in form so the field can be prefilled next
+ * time (the password is never stored).
+ *
+ * @remarks
+ * Storage-agnostic: the helpers take a minimal async key/value store that {@link KitStorageService}
+ * satisfies structurally, so they stay pure and unit-testable without DI. `kitRememberEmail`
+ * **validates the address before persisting** — a malformed or partial string is silently ignored,
+ * so a garbage entry (or a fat-fingered attempt) never becomes the next prefill. A well-formed email
+ * that later fails to sign in is still remembered by design: the user simply re-enters/corrects it.
+ *
+ * These live in the main entry (next to {@link KitStorageService}) rather than in `auth-firebase`,
+ * so the `KitAutofillDirective` can consume them without the main entry depending on the Firebase
+ * entry.
+ */
+/** Storage key under which the last entered sign-in email is kept. */
+const KIT_LAST_AUTH_EMAIL_KEY = 'kit:last-auth-email';
+/**
+ * Angular's `Validators.email` pattern — a pragmatic, RFC-5322-inspired address check. Kept in sync
+ * with `@angular/forms` so a value we persist would also pass the form's own email validation.
+ */
+const EMAIL_REGEXP = /^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(?:\.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+/** Whether `email` is a well-formed address (matches `@angular/forms` `Validators.email`). */
+const kitIsValidEmail = (email) => EMAIL_REGEXP.test(email);
+/**
+ * Persist the entered email for next time — but only when it is a well-formed address.
+ *
+ * @param store - the app's storage (e.g. `KitStorageService`)
+ * @param email - the entered email; ignored (not stored) when malformed
+ * @returns `true` when the value passed validation and was stored, `false` when it was ignored
+ */
+const kitRememberEmail = async (store, email) => {
+    if (!kitIsValidEmail(email)) {
+        return false;
+    }
+    await store.set(KIT_LAST_AUTH_EMAIL_KEY, email);
+    return true;
+};
+/**
+ * Recall the last remembered email.
+ *
+ * @param store - the app's storage (e.g. `KitStorageService`)
+ * @returns the stored email, or `null` when none has been remembered
+ */
+const kitRecallEmail = (store) => store.get(KIT_LAST_AUTH_EMAIL_KEY);
+/**
+ * Forget the remembered email.
+ *
+ * @remarks
+ * Called when the user intentionally clears or invalidates the field, so a stale prefill is not
+ * resurrected next time.
+ *
+ * @param store - the app's storage (e.g. `KitStorageService`)
+ */
+const kitForgetEmail = (store) => store.remove(KIT_LAST_AUTH_EMAIL_KEY);
+
 /**
  * Injection token carrying the {@link KitOverlayConfig} for `KitOverlayController`.
  *
@@ -661,41 +718,73 @@ const kitPresentLanguageActionSheet = async (actionSheetCtrl, options) => {
 };
 
 /**
- * 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.
+ * Input conveniences for an `ion-input` in a sign-in / sign-up form, applied via the `kitAuthInput`
+ * attribute. The mode is a typed union so a typo is a compile-time error.
+ *
+ * 1. **iOS autofill propagation (always on, every mode).** On iOS, when the browser autofills an
+ *    `ion-input` (e.g. a saved password) the value is written to the underlying native `<input>`
+ *    but the `change` event is not forwarded to the host `ion-input`, so the Angular form model
+ *    never sees it. This directive mirrors the first inner-input `change` back onto the host,
+ *    restoring two-way binding. It is a no-op on every other platform.
+ *
+ * 2. **Remember / prefill the email (`'email'` and `'email-remember'`).**
+ *    - `'email'` (sign-in) — on init recalls the last entered email and, *only while the field is
+ *      still empty*, seeds it via the bound Signal Forms field, so a browser/OS autofill the user
+ *      actually picks always wins over the prefill. On every committed change (`ionChange`) it
+ *      remembers a well-formed address, or **forgets** the stored one when the field is cleared
+ *      (empty after trim) or holds an invalid address — the user intentionally removing the prefill.
+ *    - `'email-remember'` (sign-up) — remembers a well-formed address on change, but never prefills
+ *      and never forgets. So the first-sign-up address is captured without pre-populating a
+ *      stranger's email into a new-account form, and clearing the field does not wipe an email
+ *      remembered elsewhere.
+ *
+ *    A well-formed email is persisted even if it later fails to sign in — by design; the user simply
+ *    re-enters it. A malformed/partial entry is never stored (see {@link kitRememberEmail}).
  *
  * @example
  * ```html
- * <ion-input rdlaboAutofill type="password" [(ngModel)]="password"></ion-input>
+ * <!-- sign-in email: iOS autofill + prefill + remember/forget -->
+ * <ion-input type="email" autocomplete="email" kitAuthInput="email" [formField]="form.email" />
+ * <!-- sign-up email: remember only -->
+ * <ion-input type="email" autocomplete="email" kitAuthInput="email-remember" [formField]="form.email" />
+ * <!-- password: iOS autofill propagation only -->
+ * <ion-input type="password" autocomplete="current-password" kitAuthInput="autofill" [formField]="form.password" />
  * ```
+ *
+ * @remarks
+ * Prefill writes through the Signal Forms `FORM_FIELD` bound on the same element; with no such field
+ * (e.g. `ngModel` / reactive forms) prefill is skipped — remember/forget still work off the DOM
+ * event. Storage is resolved lazily so the iOS mirror still works in apps without `@ionic/storage`.
  */
-class KitAutofillDirective {
-    #el = inject(ElementRef);
-    constructor() { }
+class KitAuthInputDirective {
+    #el;
+    #injector;
+    /** The Signal Forms field bound on this same element, if any (used to seed the prefill). */
+    #field;
+    constructor() {
+        this.#el = inject(ElementRef);
+        this.#injector = inject(Injector);
+        /** The Signal Forms field bound on this same element, if any (used to seed the prefill). */
+        this.#field = inject(FORM_FIELD, { optional: true, self: true });
+        /** Mode selector; see {@link KitAuthInputMode}. */
+        this.kitAuthInput = input('autofill', ...(ngDevMode ? [{ debugName: "kitAuthInput" }] : /* istanbul ignore next */ []));
+        /** Whether this instance persists the entered email (`'email'` or `'email-remember'`). */
+        this.#remembers = computed(() => {
+            const mode = this.kitAuthInput();
+            return mode === 'email' || mode === 'email-remember';
+        }, ...(ngDevMode ? [{ debugName: "#remembers" }] : /* istanbul ignore next */ []));
+        /** Whether this instance prefills the field from storage (`'email'` only). */
+        this.#prefills = computed(() => this.kitAuthInput() === 'email', ...(ngDevMode ? [{ debugName: "#prefills" }] : /* istanbul ignore next */ []));
+        /** Whether clearing/invalidating the field forgets the stored email (`'email'` only). */
+        this.#forgetsOnClear = computed(() => this.kitAuthInput() === 'email', ...(ngDevMode ? [{ debugName: "#forgetsOnClear" }] : /* istanbul ignore next */ []));
+    }
     /**
-     * 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.
+     * Register the iOS autofill workaround and, in `'email'` mode, seed the field from storage.
      */
     ngOnInit() {
+        if (this.#prefills()) {
+            void this.#prefillEmail();
+        }
         if (Capacitor.getPlatform() !== 'ios') {
             return;
         }
@@ -714,16 +803,75 @@ class KitAutofillDirective {
             }
         }, 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 }); }
+    /**
+     * On every committed change (`ionChange`): remember a well-formed email, or — only in the
+     * prefilling `'email'` (sign-in) mode — forget the stored one when the field is cleared or invalid,
+     * which is the user intentionally removing the prefill. `'email-remember'` never forgets, so
+     * editing the sign-up field cannot wipe an email remembered from sign-in.
+     */
+    onIonChange(event) {
+        if (!this.#remembers()) {
+            return;
+        }
+        const storage = this.#resolveStorage();
+        if (!storage) {
+            return;
+        }
+        const value = event.detail?.value ?? '';
+        if (value.trim().length > 0 && kitIsValidEmail(value)) {
+            void kitRememberEmail(storage, value);
+        }
+        else if (this.#forgetsOnClear()) {
+            void kitForgetEmail(storage);
+        }
+    }
+    /** Whether this instance persists the entered email (`'email'` or `'email-remember'`). */
+    #remembers;
+    /** Whether this instance prefills the field from storage (`'email'` only). */
+    #prefills;
+    /** Whether clearing/invalidating the field forgets the stored email (`'email'` only). */
+    #forgetsOnClear;
+    /** Resolve `KitStorageService` lazily; returns `null` when storage is not configured. */
+    #resolveStorage() {
+        try {
+            return this.#injector.get(KitStorageService);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Seed the bound field with the remembered email, but only while it is still empty — so a value
+     * the browser/OS autofills during the async recall is not clobbered.
+     */
+    async #prefillEmail() {
+        const field = this.#field;
+        if (!field) {
+            return;
+        }
+        const storage = this.#resolveStorage();
+        if (!storage) {
+            return;
+        }
+        const last = await kitRecallEmail(storage);
+        const state = field.state();
+        if (last && !state.value()) {
+            state.value.set(last);
+        }
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitAuthInputDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.17", type: KitAuthInputDirective, isStandalone: true, selector: "[kitAuthInput]", inputs: { kitAuthInput: { classPropertyName: "kitAuthInput", publicName: "kitAuthInput", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "ionChange": "onIonChange($event)" } }, ngImport: i0 }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitAutofillDirective, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitAuthInputDirective, decorators: [{
             type: Directive,
             args: [{
-                    selector: '[rdlaboAutofill]',
+                    selector: '[kitAuthInput]',
                     standalone: true,
                 }]
-        }], ctorParameters: () => [] });
+        }], ctorParameters: () => [], propDecorators: { kitAuthInput: [{ type: i0.Input, args: [{ isSignal: true, alias: "kitAuthInput", required: false }] }], onIonChange: [{
+                type: HostListener,
+                args: ['ionChange', ['$event']]
+            }] } });
 
 const keyboardWillShow = (elementRef, type) => Keyboard.addListener('keyboardWillShow', (info) => {
     if (Capacitor.getPlatform() === 'android') {
@@ -1386,5 +1534,5 @@ const kitCreateDidEnter = (el) => {
  * Generated bundle index. Do not edit.
  */
 
-export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KitAutofillDirective, KitLoadingController, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, disableHandler, kitAuthInterceptor, kitChangeEventDisabled, kitCreateDidEnter, kitImpact, kitKeyboardInit, kitPresentAuthFailedAlert, kitPresentLanguageActionSheet, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, objectEqual, provideKitAuth, provideKitHttp, provideKitOverlay };
+export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_LAST_AUTH_EMAIL_KEY, KIT_OVERLAY_CONFIG, KitAuthInputDirective, KitLoadingController, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, disableHandler, kitAuthInterceptor, kitChangeEventDisabled, kitCreateDidEnter, kitForgetEmail, kitImpact, kitIsValidEmail, kitKeyboardInit, kitPresentAuthFailedAlert, kitPresentLanguageActionSheet, kitRecallEmail, kitRememberEmail, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, objectEqual, provideKitAuth, provideKitHttp, provideKitOverlay };
 //# sourceMappingURL=rdlabo-ionic-angular-kit.mjs.map