@rdlabo/ionic-angular-kit 0.0.15 → 0.0.17

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@rdlabo/ionic-angular-kit",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
+    "@angular/forms": "^21.0.0",
     "@angular/router": "^21.0.0",
     "@ionic/angular": "^8.0.0",
     "@ionic/storage-angular": "^4.0.0",
+    "@angular/fire": ">=21.0.0-rc.0",
+    "firebase": "^11.0.0",
     "@capacitor/core": ">=6.0.0 <9.0.0",
     "@capacitor/haptics": ">=6.0.0 <9.0.0",
     "@capacitor/keyboard": ">=6.0.0 <9.0.0",
@@ -14,11 +17,19 @@
     "@capacitor/preferences": ">=6.0.0 <9.0.0",
     "@capacitor/status-bar": ">=6.0.0 <9.0.0",
     "@capacitor-community/in-app-review": ">=6.0.0 <9.0.0",
+    "@capacitor-community/facebook-login": ">=8.0.0 <9.0.0",
+    "@capacitor-community/apple-sign-in": "*",
     "@rdlabo/capacitor-brotherprint": ">=6.0.0 <9.0.0",
     "dom-to-image-more": "^3.0.0",
     "rxjs": "^7.8.0"
   },
   "peerDependenciesMeta": {
+    "@angular/fire": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
     "@capacitor/preferences": {
       "optional": true
     },
@@ -28,6 +39,12 @@
     "@capacitor-community/in-app-review": {
       "optional": true
     },
+    "@capacitor-community/facebook-login": {
+      "optional": true
+    },
+    "@capacitor-community/apple-sign-in": {
+      "optional": true
+    },
     "@rdlabo/capacitor-brotherprint": {
       "optional": true
     },
@@ -49,6 +66,14 @@
       "types": "./types/rdlabo-ionic-angular-kit.d.ts",
       "default": "./fesm2022/rdlabo-ionic-angular-kit.mjs"
     },
+    "./auth-firebase": {
+      "types": "./types/rdlabo-ionic-angular-kit-auth-firebase.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-auth-firebase.mjs"
+    },
+    "./auth-firebase/social": {
+      "types": "./types/rdlabo-ionic-angular-kit-auth-firebase-social.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-auth-firebase-social.mjs"
+    },
     "./printer": {
       "types": "./types/rdlabo-ionic-angular-kit-printer.d.ts",
       "default": "./fesm2022/rdlabo-ionic-angular-kit-printer.mjs"

package/types/rdlabo-ionic-angular-kit-auth-firebase-social.d.ts

@@ -0,0 +1,104 @@
+import { Auth } from 'firebase/auth';
+
+/** How a social-credential failure is classified for the app's error hook. */
+type KitOAuthErrorCategory = 'already-in-use' | 'cancelled' | 'other';
+/** The mode a social login runs in. */
+type KitOAuthModeName = 'new' | 'link' | 'credential';
+/**
+ * The mode discriminator. `'credential'` links an email/password to the (re-authenticated) social
+ * account, so it requires the new email/password; `'new'` / `'link'` do not.
+ */
+type KitOAuthMode = {
+    mode: 'new';
+} | {
+    mode: 'link';
+} | {
+    mode: 'credential';
+    emailLogin: {
+        email: string;
+        password: string;
+    };
+};
+/**
+ * The apple identity payload handed to the `success` hook for the backend call. Populated from the
+ * native plugin on device, or synthesized from the popup result on the web.
+ */
+interface KitAppleResponse {
+    user: string | null;
+    email: string | null;
+    givenName: string | null;
+    familyName: string | null;
+    identityToken: string | null;
+    authorizationCode: string | null;
+}
+/**
+ * The uniform lifecycle hooks for a social flow — the same `before / success / error / finally`
+ * shape as {@link KitFirebaseAuthService}'s hooks, so a call site reads the same everywhere. All are
+ * optional; the kit renders nothing itself.
+ *
+ * @typeParam Info - the identity payload handed to {@link success} (Facebook access token / Apple
+ * response), so an app can notify its backend and give feedback in one place.
+ *
+ * @remarks
+ * `before` runs before the plugin login starts, `success` after the mode's Firebase op succeeds
+ * (carrying the identity payload — do the backend call and the toast here), `error` on a classified
+ * failure (`'cancelled'` is passed through so the app can stay silent on a user cancel), and
+ * `finally` always. The kit swallows none of these errors.
+ */
+interface KitSocialHooks<Info> {
+    before?: () => void | Promise<unknown>;
+    success?: (info: Info) => void | Promise<unknown>;
+    error?: (category: KitOAuthErrorCategory, error: unknown) => void | Promise<unknown>;
+    finally?: () => void | Promise<unknown>;
+}
+/** Options for {@link kitFacebookLogin}. */
+type KitFacebookLoginOptions = KitOAuthMode & KitSocialHooks<{
+    accessToken: string;
+    mode: KitOAuthModeName;
+}> & {
+    /** Facebook permissions to request. */
+    permissions: string[];
+};
+/** Options for {@link kitAppleLogin}. */
+type KitAppleLoginOptions = KitOAuthMode & KitSocialHooks<{
+    response: KitAppleResponse;
+    mode: KitOAuthModeName;
+}>;
+/**
+ * Facebook login / link, bundled: native plugin → credential → the shared 3-mode state machine.
+ *
+ * @remarks
+ * On iOS the credential is built from the OIDC token with a nonce (`OAuthProvider('facebook.com')`);
+ * elsewhere from the access token (`FacebookAuthProvider`). Returns `{ status: false }` on a
+ * cancelled/failed plugin login or a handled Firebase error (the app was already notified via the
+ * hooks).
+ */
+declare const kitFacebookLogin: (auth: Auth, options: KitFacebookLoginOptions) => Promise<{
+    status: boolean;
+}>;
+/**
+ * Log out of the Facebook SDK (best-effort; errors are ignored).
+ *
+ * @remarks
+ * Apps that offer Facebook login typically call this alongside the Firebase sign-out, so it lives
+ * here to keep the `@capacitor-community/facebook-login` import out of the app.
+ */
+declare const kitFacebookLogout: () => Promise<void>;
+/**
+ * Sign in with Apple / link, bundled. Native uses the plugin; the web uses the Firebase popup.
+ *
+ * @remarks
+ * - **Native**: `SignInWithApple.authorize()` → `OAuthProvider('apple.com')` credential → the shared
+ *   3-mode state machine.
+ * - **Web**: `signInWithPopup` / `linkWithPopup` (with `email`/`name` scopes), or, for `credential`,
+ *   `reauthenticateWithPopup` then link the email/password. The identity payload for the backend is
+ *   synthesized from the popup result.
+ *
+ * Every failure path (including popup errors) is routed through `onError`.
+ */
+declare const kitAppleLogin: (auth: Auth, options: KitAppleLoginOptions) => Promise<{
+    status: boolean;
+}>;
+
+export { kitAppleLogin, kitFacebookLogin, kitFacebookLogout };
+export type { KitAppleLoginOptions, KitAppleResponse, KitFacebookLoginOptions, KitOAuthErrorCategory, KitOAuthMode, KitOAuthModeName };

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

@@ -0,0 +1,266 @@
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { FirebaseOptions } from '@angular/fire/app';
+import { Auth, User, UserCredential } from 'firebase/auth';
+import { Observable } from 'rxjs';
+
+/**
+ * DI token for the Firebase `Auth` instance.
+ *
+ * @remarks
+ * Inject this (`inject(KIT_FIREBASE_AUTH)`) instead of `@angular/fire`'s `Auth`, so the
+ * `@angular/fire` dependency stays isolated inside the kit. This is the seam that makes the planned
+ * `@angular/fire` → `firebase/auth` migration a kit-internal change: only {@link provideKitFirebase}
+ * (which binds this token) has to change; every consumer keeps injecting `KIT_FIREBASE_AUTH`.
+ *
+ * The value is a `firebase/auth` `Auth` (the SDK type is exposed directly, not re-abstracted —
+ * Firebase Auth itself is not being dropped, only the `@angular/fire` wrapper).
+ */
+declare const KIT_FIREBASE_AUTH: InjectionToken<Auth>;
+/** Configuration for {@link provideKitFirebase}. */
+interface KitFirebaseConfig {
+    /** The Firebase project options (`apiKey`, `authDomain`, `projectId`, …). */
+    readonly firebaseConfig: FirebaseOptions;
+}
+/**
+ * Wire Firebase App + Auth into the application and bind {@link KIT_FIREBASE_AUTH}.
+ *
+ * @remarks
+ * Replaces each app's hand-rolled `provideFirebaseApp(...)` + `provideAuth(...)` (with its
+ * native/web persistence branch) with one call, and — crucially — keeps `@angular/fire` out of the
+ * application: apps inject {@link KIT_FIREBASE_AUTH} and import auth operations/types straight from
+ * `firebase/auth`. On a native platform the persistence uses `indexedDBLocalPersistence`; on the web
+ * it uses the default (`getAuth`).
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideKitFirebase({ firebaseConfig: environment.firebase })],
+ * });
+ * ```
+ */
+declare const provideKitFirebase: (config: KitFirebaseConfig) => EnvironmentProviders;
+/**
+ * Wire Firebase Analytics into the application (optional; only the apps that use it call this).
+ */
+declare const provideKitFirebaseAnalytics: () => EnvironmentProviders;
+
+/** A user-facing message (alert header + body). */
+interface KitAuthMessage {
+    readonly header: string;
+    readonly message: string;
+}
+/**
+ * The fleet's canonical Firebase auth error dictionary: error `code` → message, plus a fallback for
+ * unmapped codes.
+ *
+ * @remarks
+ * The kit does *not* present errors itself (that's an app side effect). This is offered as an
+ * importable constant so an app can render its error alert from a shared, canonical source instead of
+ * re-declaring the same five messages. Apps that need `$localize` (i18n) keep their own dictionary;
+ * JA-only apps can import {@link KIT_DEFAULT_AUTH_TEXT} and spread it, overriding the odd code.
+ *
+ * @example
+ * ```ts
+ * import { KIT_DEFAULT_AUTH_TEXT } from '@rdlabo/ionic-angular-kit/auth-firebase';
+ *
+ * const AUTH_ERRORS = { ...KIT_DEFAULT_AUTH_TEXT.errors, 'auth/wrong-password': { header: '…', message: '…' } };
+ * presentError(code: string) {
+ *   const msg = AUTH_ERRORS[code] ?? KIT_DEFAULT_AUTH_TEXT.fallbackError;
+ *   return this.overlay.alertClose(msg);
+ * }
+ * ```
+ */
+interface KitAuthText {
+    /** Firebase error `code` → message. */
+    readonly errors: Readonly<Record<string, KitAuthMessage>>;
+    /** Shown when an error has no matching `code`. */
+    readonly fallbackError: KitAuthMessage;
+}
+/** The fleet's canonical Japanese error dictionary (see {@link KitAuthText}). */
+declare const KIT_DEFAULT_AUTH_TEXT: KitAuthText;
+
+/**
+ * Uniform lifecycle hooks for the bundled email/password auth flows — where the app hangs its own
+ * side effects on a flow.
+ *
+ * @remarks
+ * The kit performs the Firebase operation and renders nothing itself. `before` runs before the op,
+ * `success` on success, `error` on failure (with the raw error — the app presents it, from its own
+ * dictionary), and `finally` always. Failures are *not* thrown: value flows resolve to `null` and
+ * boolean flows to `false`. Return values are awaited and ignored.
+ *
+ * @example
+ * ```ts
+ * kitSignIn(auth, email, password, {
+ *   error: (e) => this.presentAuthError(e),   // app's own error dictionary
+ *   success: () => this.nav.navigateRoot('/'),
+ * });
+ * ```
+ */
+interface KitAuthHooks {
+    before?: () => void | Promise<unknown>;
+    success?: () => void | Promise<unknown>;
+    error?: (error: unknown) => void | Promise<unknown>;
+    finally?: () => void | Promise<unknown>;
+}
+/**
+ * Sign in with email and password.
+ *
+ * @remarks
+ * Bundles the Firebase op so the app never imports `signInWithEmailAndPassword` directly (the SDK
+ * stays isolated in the kit). Resolves the credential, or `null` on failure (handed to the `error`
+ * hook).
+ */
+declare const kitSignIn: (auth: Auth, email: string, password: string, hooks?: KitAuthHooks) => Promise<UserCredential | null>;
+/**
+ * Create an account and send the verification email.
+ *
+ * @remarks
+ * Bundles the two-step "create → send verification" sequence. Resolves the credential, or `null` on
+ * failure. Any success toast is the caller's, via the `success` hook.
+ */
+declare const kitSignUp: (auth: Auth, email: string, password: string, hooks?: KitAuthHooks) => Promise<UserCredential | null>;
+/**
+ * Sign out.
+ *
+ * @remarks
+ * App-specific cleanup (clearing stores, toasts, navigation, third-party logout) is the caller's,
+ * done via the hooks — the kit only owns the Firebase op. `true` on success, `false` on failure.
+ */
+declare const kitSignOut: (auth: Auth, hooks?: KitAuthHooks) => Promise<boolean>;
+/** Send a password-reset email. `true` on success, `false` on failure. */
+declare const kitSendPasswordReset: (auth: Auth, email: string, hooks?: KitAuthHooks) => Promise<boolean>;
+/**
+ * Unlink a linked auth provider (e.g. `'facebook.com'`, `'apple.com'`) from the current user.
+ *
+ * @remarks
+ * Exposed from the core (not `/social`) so an app can unlink without importing `unlink` from
+ * `firebase/auth` directly — keeping the invariant that the SDK is only imported inside the kit. Any
+ * app-specific step around it (e.g. a backend DELETE before unlinking) goes in the `before` hook.
+ * Resolves the updated `User`, or `null` on failure (including when there is no signed-in user).
+ */
+declare const kitUnlinkProvider: (auth: Auth, providerId: string, hooks?: KitAuthHooks) => Promise<User | null>;
+/**
+ * (Re-)send the verification email to the signed-in user (a no-op when signed out).
+ *
+ * @remarks
+ * `true` on success (including the signed-out no-op), `false` on failure.
+ */
+declare const kitSendEmailVerification: (auth: Auth, hooks?: KitAuthHooks) => Promise<boolean>;
+/**
+ * The current Firebase user as an Observable (emits on every auth-state change; `null` when signed out).
+ *
+ * @remarks
+ * Wraps `onAuthStateChanged` so consumers get an rxjs stream without pulling in `@angular/fire`'s
+ * `authState` (or `rxfire`). Emits the current value on subscribe and completes its listener on
+ * teardown.
+ *
+ * @param auth - the Firebase `Auth` instance (inject `KIT_FIREBASE_AUTH`)
+ */
+declare const kitAuthState: (auth: Auth) => Observable<User | null>;
+/**
+ * The current user's ID token, or `null` when signed out.
+ *
+ * @remarks
+ * For building `Authorization` / bearer headers in interceptors and services. Failure to fetch a
+ * token is **thrown, not swallowed** — the caller decides the fallback (e.g. an empty header) as its
+ * own side effect, so the kit never silently hides an auth failure.
+ *
+ * @param auth - the Firebase `Auth` instance (inject `KIT_FIREBASE_AUTH`)
+ * @param forceRefresh - force a token refresh (default `false`)
+ * @returns the ID token, or `null` if there is no signed-in user
+ * @throws if the token fetch fails for a signed-in user
+ */
+declare const kitGetIdToken: (auth: Auth, forceRefresh?: boolean) => Promise<string | null>;
+/**
+ * The app-supplied side effects for {@link kitReauthWithRetry}.
+ *
+ * @remarks
+ * The kit owns the *control flow* but generates no UI; every user-facing effect (the prompt, the
+ * loading overlay) is a callback the app implements, rendering from its own dictionary.
+ */
+interface KitReauthWithRetryOptions {
+    /**
+     * Present the current-password prompt.
+     *
+     * @remarks
+     * A side effect — the app presents whatever it likes (e.g. an `ion-alert` with a masked input and
+     * dictionary text). Receives `true` when re-prompting after a wrong password.
+     *
+     * @returns the entered password, or `null` if the user cancels/dismisses
+     */
+    prompt: (wrongPasswordRetry: boolean) => Promise<string | null>;
+    /**
+     * The sensitive change to run once re-authenticated.
+     *
+     * @remarks
+     * Keep this pure — just the Firebase op(s) (e.g. `updatePassword(user, next)`). Loading and other
+     * UI are side effects handled by {@link withLoading}, not here.
+     */
+    mutate: (user: User) => Promise<void>;
+    /**
+     * Wrap the re-authentication + mutation with a loading indicator (a side effect).
+     *
+     * @remarks
+     * Optional. Runs only after a password is entered, around each attempt — so no loading flashes on a
+     * cancelled prompt, and it re-shows on a wrong-password retry. The app implements it (e.g.
+     * present/dismiss an `ion-loading`).
+     */
+    withLoading?: (run: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Run the fleet's canonical "confirm current password → change" flow, re-prompting in place on a
+ * wrong password.
+ *
+ * @remarks
+ * Owns the drift-prone *control flow* (the retry loop, the wrong-password classification every app
+ * once got wrong, and when to show loading) while generating **no UI** — the prompt and the loading
+ * overlay are {@link KitReauthWithRetryOptions | side-effect callbacks} the app supplies. On a wrong
+ * password the loop re-prompts instead of dropping the user out of the flow. Any non-wrong-password
+ * re-auth failure (lockout, offline, expired session) and any error from `mutate` are re-thrown —
+ * re-auth failures unwrapped to the underlying Firebase error so the caller's error dictionary can
+ * read its `code`.
+ *
+ * @param auth - the Firebase `Auth` instance
+ * @param currentEmail - the current email (for the re-auth credential)
+ * @param options - the pure mutation plus the app's prompt / loading side effects
+ * @returns `true` if the mutation completed, `false` if the user cancelled
+ * @throws the underlying Firebase error on a non-wrong-password failure, or `mutate`'s own error
+ */
+declare const kitReauthWithRetry: (auth: Auth, currentEmail: string, options: KitReauthWithRetryOptions) => Promise<boolean>;
+/** The fleet's 3-state auth status derived from the Firebase user. */
+type KitAuthStatus = 'user' | 'confirm' | 'required';
+/** Options for {@link kitResolveAuthStatus}. */
+interface KitResolveAuthStatusOptions {
+    /**
+     * Provider IDs that count as verified even without `emailVerified` — a social login (e.g.
+     * `'facebook.com'`, `'apple.com'`) has no email-verification step but is a real, trusted account.
+     */
+    readonly verifiedProviders?: readonly string[];
+    /**
+     * Extra predicate to treat a signed-in user as fully authed regardless of verification — for an
+     * e2e bypass or an anonymous-allowed app. Receives the current user.
+     */
+    readonly allowWhen?: (user: User) => boolean;
+}
+/**
+ * Classify a Firebase user into the fleet's 3-state auth status.
+ *
+ * @remarks
+ * `null` (signed out) → `'required'`. A signed-in user is `'user'` when their email is verified, OR
+ * they signed in with one of `verifiedProviders`, OR `allowWhen` returns true; otherwise `'confirm'`
+ * (signed in but unverified). This is only the shared classification — app-specific side effects
+ * around it (reloading the user to refresh `emailVerified`, caching a token) stay in the app.
+ *
+ * @example
+ * ```ts
+ * kitResolveAuthStatus(user, {
+ *   verifiedProviders: ['facebook.com', 'apple.com'],
+ *   allowWhen: () => environment.e2e,
+ * });
+ * ```
+ */
+declare const kitResolveAuthStatus: (user: User | null, options?: KitResolveAuthStatusOptions) => KitAuthStatus;
+
+export { KIT_DEFAULT_AUTH_TEXT, KIT_FIREBASE_AUTH, kitAuthState, kitGetIdToken, kitReauthWithRetry, kitResolveAuthStatus, kitSendEmailVerification, kitSendPasswordReset, kitSignIn, kitSignOut, kitSignUp, kitUnlinkProvider, provideKitFirebase, provideKitFirebaseAnalytics };
+export type { KitAuthHooks, KitAuthMessage, KitAuthStatus, KitAuthText, KitFirebaseConfig, KitReauthWithRetryOptions, KitResolveAuthStatusOptions };

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

@@ -79,6 +79,57 @@ declare class KitStorageService {
     static ɵprov: i0.ɵɵInjectableDeclaration<KitStorageService>;
 }
 
+/**
+ * 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.
+ */
+/** Minimal async key/value store — structurally satisfied by `KitStorageService`. */
+interface KitEmailStore {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** Storage key under which the last entered sign-in email is kept. */
+declare const KIT_LAST_AUTH_EMAIL_KEY = "kit:last-auth-email";
+/** Whether `email` is a well-formed address (matches `@angular/forms` `Validators.email`). */
+declare const kitIsValidEmail: (email: string) => boolean;
+/**
+ * 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
+ */
+declare const kitRememberEmail: (store: KitEmailStore, email: string) => Promise<boolean>;
+/**
+ * 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
+ */
+declare const kitRecallEmail: (store: KitEmailStore) => Promise<string | null>;
+/**
+ * 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`)
+ */
+declare const kitForgetEmail: (store: KitEmailStore) => Promise<void>;
+
 /**
  * User-visible button labels consumed by `KitOverlayController`.
  *
@@ -603,43 +654,70 @@ interface KitLanguageActionSheetOptions {
 declare const kitPresentLanguageActionSheet: (actionSheetCtrl: ActionSheetController, options: KitLanguageActionSheetOptions) => Promise<void>;
 
 /**
- * Work around iOS `ion-input` autofill values not propagating to the Angular form model.
+ * The mode of {@link KitAuthInputDirective}.
  *
- * 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.
+ * - `'autofill'` — iOS autofill propagation only (use on the password input).
+ * - `'email'` — sign-in email: prefill from storage + remember on change + forget when cleared.
+ * - `'email-remember'` — sign-up email: remember on change only (no prefill, no forget).
+ */
+type KitAuthInputMode = 'autofill' | 'email' | 'email-remember';
+/**
+ * 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`.
  */
-declare class KitAutofillDirective implements OnInit {
+declare class KitAuthInputDirective implements OnInit {
     #private;
+    /** Mode selector; see {@link KitAuthInputMode}. */
+    readonly kitAuthInput: i0.InputSignal<KitAuthInputMode>;
     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.
+     * Register the iOS autofill workaround and, in `'email'` mode, seed the field from storage.
      */
     ngOnInit(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KitAutofillDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<KitAutofillDirective, "[rdlaboAutofill]", never, {}, {}, never, never, true, never>;
+    /**
+     * 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: Event): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitAuthInputDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KitAuthInputDirective, "[kitAuthInput]", never, { "kitAuthInput": { "alias": "kitAuthInput"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -1236,5 +1314,5 @@ declare const kitChangeEventDisabled: (completeEvent: WritableSignal<HTMLIonInfi
  */
 declare const kitCreateDidEnter: (el: ElementRef) => Observable<boolean>;
 
-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 type { KitAlertCloseOptions, KitAlertConfirmOptions, KitAuthConfig, KitAuthFailedAlertOptions, KitAuthRedirects, KitAuthState, KitHttpConfig, KitKeyboardAdjust, KitLabels, KitLanguageActionSheetOptions, KitLanguageOption, KitModalPresentOptions, KitOverlayConfig, KitReloadAlertOptions, ModalMetadata };
+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 };
+export type { KitAlertCloseOptions, KitAlertConfirmOptions, KitAuthConfig, KitAuthFailedAlertOptions, KitAuthInputMode, KitAuthRedirects, KitAuthState, KitEmailStore, KitHttpConfig, KitKeyboardAdjust, KitLabels, KitLanguageActionSheetOptions, KitLanguageOption, KitModalPresentOptions, KitOverlayConfig, KitReloadAlertOptions, ModalMetadata };