@rdlabo/ionic-angular-kit 0.0.1 → 0.0.3

package/README.md

@@ -265,31 +265,36 @@ A fleet-canonical HTTP interceptor with:
 
 **Convention:** all app-specific logic (auth headers, error UI) lives in the config factory. The retry policy, bypass evaluation, and error dispatch are fixed in the kit and not overridable per-call.
 
+**Only `getAuthHeaders` is required.** Every other hook is optional and defaults to a safe no-op (`buildExtraHeaders` → `{}`, `bypass` → `false`, `offlineFallback` → `null`), so a config specifies only the behavior that actually differs from the baseline.
+
 **Setup**
 
 ```typescript
 // app.config.ts
 import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { kitAuthInterceptor, provideKitHttp } from '@rdlabo/ionic-angular-kit';
+import { kitAuthInterceptor, provideKitHttp, KitReloadAlertController } from '@rdlabo/ionic-angular-kit';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideHttpClient(withInterceptors([kitAuthInterceptor])),
     provideKitHttp(() => {
       const auth = inject(AuthService);
-      const router = inject(Router);
-      const toast = inject(KitOverlayController);
+      const reload = inject(KitReloadAlertController);
       return {
-        bypass: (req) => req.url.startsWith('https://cdn.example.com'),
         getAuthHeaders: async (req) => ({
           Authorization: `Bearer ${await auth.getToken()}`,
         }),
-        buildExtraHeaders: (req) => ({ 'X-App-Version': '1.0.0' }),
-        offlineFallback: (req, err) => null,   // no offline queue
         onUnauthorized: (req) => auth.signOut(),
-        onForbidden: (req) => router.navigate(['/403']),
-        onNetworkError: (status) => toast.presentToast({ message: 'Network error' }),
-        onServerError: (message) => toast.presentToast({ message }),
+        // Fleet-canonical "network error → offer reload" (see KitReloadAlertController).
+        onNetworkError: (status) =>
+          reload.present({
+            header: 'ネットワークエラー',
+            message: `通信できませんでした。リフレッシュしますか？（${status}）`,
+            okText: 'リフレッシュ',
+          }),
+        // Auto-dismiss the stale alert once connectivity is back.
+        onResponse: () => void reload.dismiss(),
+        // buildExtraHeaders / bypass / offlineFallback / onForbidden / onServerError omitted → kit defaults.
       };
     }),
   ],
@@ -303,6 +308,30 @@ export const appConfig: ApplicationConfig = {
 4. Non-400/500 status AND device connected → `onNetworkError`
 5. 400 or 500 with `error.message` → `onServerError`
 
+### KitReloadAlertController
+
+The fleet's canonical "network error → offer to reload" alert, as a stateful controller that unifies the good-UX variant that had drifted across apps:
+
+- **De-dup** — never stacks; a second `present()` while one is showing is a no-op.
+- **Backdrop lock** — `backdropDismiss: false`, so a critical error isn't dismissed by an accidental backdrop tap.
+- **Auto-dismiss on reconnect** — `dismiss()` (called from a later successful response) clears a now-stale error alert.
+- **Reload on confirm** — the confirm button calls `location.reload()`; cancel uses the configured `labels.cancel`.
+
+All text is passed in, so the kit stays free of hardcoded i18n. Wire `present` from a network-class error and `dismiss` from a success (interceptor `onResponse`, or a class interceptor's success path).
+
+```typescript
+import { KitReloadAlertController } from '@rdlabo/ionic-angular-kit';
+
+const reload = inject(KitReloadAlertController);
+await reload.present({
+  header: 'ネットワークエラー',
+  message: `通信できませんでした。リフレッシュしますか？（${status}）`,
+  okText: 'リフレッシュ',
+});
+// later, on a successful response:
+await reload.dismiss();
+```
+
 ---
 
 ### KitAutofillDirective

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/kit",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/ionic-angular-kit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
@@ -16,17 +16,5 @@
   "dependencies": {
     "tslib": "^2.3.0"
   },
-  "sideEffects": false,
-  "module": "fesm2022/rdlabo-ionic-angular-kit.mjs",
-  "typings": "types/rdlabo-ionic-angular-kit.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/rdlabo-ionic-angular-kit.d.ts",
-      "default": "./fesm2022/rdlabo-ionic-angular-kit.mjs"
-    }
-  },
-  "type": "module"
-}
+  "sideEffects": false
+}

package/src/lib/auth/auth-guards.spec.ts

@@ -0,0 +1,210 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import type { ActivatedRouteSnapshot, RouterStateSnapshot, UrlTree } from '@angular/router';
+import { Router } from '@angular/router';
+import { NavController } from '@ionic/angular/standalone';
+import type { Observable } from 'rxjs';
+import { of } from 'rxjs';
+import { firstValueFrom } from 'rxjs';
+
+import {
+  type KitAuthState,
+  provideKitAuth,
+  kitRequiredUnauthorizedGuard,
+  kitRequireConfirmingGuard,
+  kitRequireAuthorizedGuard,
+} from './auth-guards';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const REDIRECTS = {
+  whenAuthorized: '/home',
+  whenConfirming: '/auth/confirm',
+  whenNotConfirming: '/auth/signin',
+  whenUnauthorized: '/auth',
+};
+
+const routeStub = {} as ActivatedRouteSnapshot;
+const stateStub = {} as RouterStateSnapshot;
+
+/**
+ * The guards always return an Observable at runtime (rxjs pipe).
+ * CanActivateFn returns `MaybeAsync<GuardResult>` which widens the compile-time type,
+ * so we cast to Observable before handing to firstValueFrom.
+ */
+function runGuard(value: unknown): Promise<boolean | UrlTree> {
+  return firstValueFrom(value as Observable<boolean | UrlTree>);
+}
+
+/** Cast a vi.fn() mock so it satisfies a typed function signature. */
+function mockFn<T>(): T {
+  return vi.fn() as unknown as T;
+}
+
+function setup(
+  state: KitAuthState,
+  {
+    onAuthorized = vi.fn().mockResolvedValue(true) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>,
+    onUnauthenticated = vi.fn().mockResolvedValue(false) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>,
+  }: {
+    onAuthorized?: (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    onUnauthenticated?: (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+  } = {},
+) {
+  const navigate = vi.fn().mockResolvedValue(true);
+  const setDirection = vi.fn();
+
+  TestBed.configureTestingModule({
+    providers: [
+      provideZonelessChangeDetection(),
+      provideKitAuth(() => ({
+        authState: () => of(state),
+        onAuthorized,
+        onUnauthenticated,
+        redirects: REDIRECTS,
+      })),
+      { provide: Router, useValue: { navigate } },
+      { provide: NavController, useValue: { setDirection } },
+    ],
+  });
+
+  return { navigate, setDirection, onAuthorized, onUnauthenticated };
+}
+
+// ---------------------------------------------------------------------------
+// kitRequiredUnauthorizedGuard
+// ---------------------------------------------------------------------------
+describe('kitRequiredUnauthorizedGuard', () => {
+  afterEach(() => TestBed.resetTestingModule());
+
+  it("'user' → navigates whenAuthorized and returns false", async () => {
+    const { navigate, setDirection } = setup('user');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequiredUnauthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).toHaveBeenCalledWith('root');
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenAuthorized]);
+  });
+
+  it("'confirm' → navigates whenConfirming and returns false (no setDirection)", async () => {
+    const { navigate, setDirection } = setup('confirm');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequiredUnauthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).not.toHaveBeenCalled();
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenConfirming]);
+  });
+
+  it("'required' → returns true", async () => {
+    setup('required');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequiredUnauthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+  });
+
+  it("'anonymous' → returns true", async () => {
+    setup('anonymous');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequiredUnauthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// kitRequireConfirmingGuard
+// ---------------------------------------------------------------------------
+describe('kitRequireConfirmingGuard', () => {
+  afterEach(() => TestBed.resetTestingModule());
+
+  it("'confirm' → returns true", async () => {
+    setup('confirm');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireConfirmingGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+  });
+
+  it("'anonymous' → navigates whenAuthorized and returns false", async () => {
+    const { navigate, setDirection } = setup('anonymous');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireConfirmingGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).toHaveBeenCalledWith('root');
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenAuthorized]);
+  });
+
+  it("'required' → navigates whenNotConfirming and returns false", async () => {
+    const { navigate, setDirection } = setup('required');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireConfirmingGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).toHaveBeenCalledWith('root');
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenNotConfirming]);
+  });
+
+  it("'user' → navigates whenNotConfirming and returns false", async () => {
+    const { navigate, setDirection } = setup('user');
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireConfirmingGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).toHaveBeenCalledWith('root');
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenNotConfirming]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// kitRequireAuthorizedGuard
+// ---------------------------------------------------------------------------
+describe('kitRequireAuthorizedGuard', () => {
+  afterEach(() => TestBed.resetTestingModule());
+
+  it("'user' → calls onAuthorized with state and returns its value (true)", async () => {
+    const onAuthorized = vi.fn().mockResolvedValue(true) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    setup('user', { onAuthorized });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+    expect(onAuthorized).toHaveBeenCalledWith(stateStub);
+  });
+
+  it("'user' → propagates UrlTree from onAuthorized", async () => {
+    const urlTree = { queryParams: {} } as unknown as UrlTree;
+    const onAuthorized = vi.fn().mockResolvedValue(urlTree) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    setup('user', { onAuthorized });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(urlTree);
+  });
+
+  it("'anonymous' → returns true without calling any hook", async () => {
+    const onAuthorized = vi.fn() as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    const onUnauthenticated = vi.fn() as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    setup('anonymous', { onAuthorized, onUnauthenticated });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+    expect(onAuthorized).not.toHaveBeenCalled();
+    expect(onUnauthenticated).not.toHaveBeenCalled();
+  });
+
+  it("'required' + onUnauthenticated → true → returns true (fallback allows)", async () => {
+    const onUnauthenticated = vi.fn().mockResolvedValue(true) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    setup('required', { onUnauthenticated });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(true);
+  });
+
+  it("'required' + onUnauthenticated → UrlTree → passes UrlTree through", async () => {
+    const urlTree = { queryParams: {} } as unknown as UrlTree;
+    const onUnauthenticated = vi.fn().mockResolvedValue(urlTree) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    setup('required', { onUnauthenticated });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(urlTree);
+  });
+
+  it("'required' + onUnauthenticated → false → navigates whenUnauthorized and returns false", async () => {
+    const onUnauthenticated = vi.fn().mockResolvedValue(false) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    const { navigate, setDirection } = setup('required', { onUnauthenticated });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(setDirection).toHaveBeenCalledWith('root');
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenUnauthorized]);
+  });
+
+  it("'confirm' + onUnauthenticated → false → navigates whenUnauthorized and returns false", async () => {
+    const onUnauthenticated = vi.fn().mockResolvedValue(false) as unknown as (s: RouterStateSnapshot) => Promise<boolean | UrlTree>;
+    const { navigate } = setup('confirm', { onUnauthenticated });
+    const result = await runGuard(TestBed.runInInjectionContext(() => kitRequireAuthorizedGuard(routeStub, stateStub)));
+    expect(result).toBe(false);
+    expect(navigate).toHaveBeenCalledWith([REDIRECTS.whenUnauthorized]);
+  });
+});

package/src/lib/auth/auth-guards.ts

@@ -0,0 +1,227 @@
+import type { EnvironmentProviders } from '@angular/core';
+import { inject, InjectionToken, makeEnvironmentProviders } from '@angular/core';
+import type { CanActivateFn, RouterStateSnapshot, UrlTree } from '@angular/router';
+import { Router } from '@angular/router';
+import { NavController } from '@ionic/angular/standalone';
+import type { Observable } from 'rxjs';
+import { map, mergeMap } from 'rxjs/operators';
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export const KIT_AUTH_CONFIG = new InjectionToken<KitAuthConfig>('@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',
+ *     },
+ *   };
+ * });
+ * ```
+ */
+export const provideKitAuth = (configFactory: () => KitAuthConfig): EnvironmentProviders =>
+  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] }];
+ * ```
+ */
+export const kitRequiredUnauthorizedGuard: CanActivateFn = () => {
+  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] }];
+ * ```
+ */
+export const kitRequireConfirmingGuard: CanActivateFn = () => {
+  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] }];
+ * ```
+ */
+export const kitRequireAuthorizedGuard: CanActivateFn = (_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;
+    }),
+  );
+};

package/src/lib/directives/autofill.directive.ts

@@ -0,0 +1,68 @@
+import type { OnInit } from '@angular/core';
+import { Directive, ElementRef, inject } from '@angular/core';
+import { Capacitor } from '@capacitor/core';
+
+/**
+ * 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>
+ * ```
+ */
+@Directive({
+  selector: '[rdlaboAutofill]',
+  standalone: true,
+})
+export class KitAutofillDirective implements OnInit {
+  readonly #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(): void {
+    if (Capacitor.getPlatform() !== 'ios') {
+      return;
+    }
+    setTimeout(() => {
+      try {
+        this.#el.nativeElement.children[0].addEventListener(
+          'change',
+          (e: Event) => {
+            this.#el.nativeElement.value = (e.target as HTMLInputElement).value;
+          },
+          {
+            capture: false,
+            once: true,
+            passive: true,
+          },
+        );
+      } catch {
+        /* empty */
+      }
+    }, 100); // Need some time for the ion-input to create the input element
+  }
+}