@rdlabo/ionic-angular-kit 0.0.2 → 0.0.3

package/src/lib/overlay/kit-overlay.controller.spec.ts

@@ -0,0 +1,233 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { AlertController, ModalController, ToastController } from '@ionic/angular/standalone';
+
+import { KitOverlayController } from './kit-overlay.controller';
+import { KIT_OVERLAY_CONFIG, provideKitOverlay } from './overlay-config';
+
+// ---------------------------------------------------------------------------
+// Mock Capacitor — KitOverlayController imports Capacitor/Keyboard for the
+// watchKeyboard feature; we stub them so no native APIs are called in jsdom.
+// ---------------------------------------------------------------------------
+vi.mock('@capacitor/core', () => ({
+  Capacitor: {
+    isNativePlatform: vi.fn().mockReturnValue(false),
+    getPlatform: vi.fn().mockReturnValue('web'),
+  },
+  registerPlugin: vi.fn().mockReturnValue({}),
+}));
+
+vi.mock('@capacitor/keyboard', () => ({
+  Keyboard: {
+    addListener: vi.fn().mockResolvedValue({ remove: vi.fn().mockResolvedValue(undefined) }),
+  },
+}));
+
+vi.mock('@capacitor/haptics', () => ({
+  Haptics: { impact: vi.fn().mockResolvedValue(undefined) },
+  ImpactStyle: { Light: 'LIGHT', Medium: 'MEDIUM', Heavy: 'HEAVY' },
+}));
+
+// ---------------------------------------------------------------------------
+// Fake overlay element factory
+// ---------------------------------------------------------------------------
+type Role = string | undefined;
+
+function fakeOverlay(role: Role = undefined, data: unknown = undefined) {
+  return {
+    present: vi.fn().mockResolvedValue(undefined),
+    onWillDismiss: vi.fn().mockResolvedValue({ role, data }),
+    onDidDismiss: vi.fn().mockResolvedValue({ role, data }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const TEST_LABELS = { close: 'Close', cancel: 'Cancel' };
+
+function setup({
+  modalOverlay = fakeOverlay(),
+  toastOverlay = fakeOverlay(),
+  alertOverlay = fakeOverlay(),
+}: {
+  modalOverlay?: ReturnType<typeof fakeOverlay>;
+  toastOverlay?: ReturnType<typeof fakeOverlay>;
+  alertOverlay?: ReturnType<typeof fakeOverlay>;
+} = {}) {
+  const modalCtrl = { create: vi.fn().mockResolvedValue(modalOverlay) };
+  const toastCtrl = { create: vi.fn().mockResolvedValue(toastOverlay) };
+  const alertCtrl = { create: vi.fn().mockResolvedValue(alertOverlay) };
+
+  TestBed.configureTestingModule({
+    providers: [
+      provideZonelessChangeDetection(),
+      KitOverlayController,
+      provideKitOverlay({ labels: TEST_LABELS }),
+      { provide: ModalController, useValue: modalCtrl },
+      { provide: ToastController, useValue: toastCtrl },
+      { provide: AlertController, useValue: alertCtrl },
+    ],
+  });
+
+  return {
+    controller: TestBed.inject(KitOverlayController),
+    modalCtrl,
+    toastCtrl,
+    alertCtrl,
+    modalOverlay,
+    toastOverlay,
+    alertOverlay,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('KitOverlayController', () => {
+  afterEach(() => {
+    TestBed.resetTestingModule();
+  });
+
+  // ---- alertConfirm ---------------------------------------------------------
+  describe('alertConfirm', () => {
+    const opts = { header: 'Confirm', message: 'Are you sure?', okText: 'OK' };
+
+    it("returns true when onWillDismiss role === 'confirm'", async () => {
+      const { controller } = setup({ alertOverlay: fakeOverlay('confirm') });
+      const result = await controller.alertConfirm(opts);
+      expect(result).toBe(true);
+    });
+
+    it("returns false when onWillDismiss role === 'cancel'", async () => {
+      const { controller } = setup({ alertOverlay: fakeOverlay('cancel') });
+      const result = await controller.alertConfirm(opts);
+      expect(result).toBe(false);
+    });
+
+    it('returns false when role is undefined (backdrop dismiss)', async () => {
+      const { controller } = setup({ alertOverlay: fakeOverlay(undefined) });
+      const result = await controller.alertConfirm(opts);
+      expect(result).toBe(false);
+    });
+
+    it('creates the alert with the correct buttons (cancel + confirm)', async () => {
+      const { controller, alertCtrl } = setup({ alertOverlay: fakeOverlay('confirm') });
+      await controller.alertConfirm(opts);
+      const createArgs = alertCtrl.create.mock.calls[0][0];
+      const roles = (createArgs.buttons as { role: string }[]).map((b) => b.role);
+      expect(roles).toContain('cancel');
+      expect(roles).toContain('confirm');
+    });
+
+    it('uses the injected cancel label', async () => {
+      const { controller, alertCtrl } = setup({ alertOverlay: fakeOverlay('cancel') });
+      await controller.alertConfirm(opts);
+      const createArgs = alertCtrl.create.mock.calls[0][0];
+      const cancelBtn = (createArgs.buttons as { text: string; role: string }[]).find((b) => b.role === 'cancel');
+      expect(cancelBtn?.text).toBe(TEST_LABELS.cancel);
+    });
+  });
+
+  // ---- alertClose -----------------------------------------------------------
+  describe('alertClose', () => {
+    it('creates and presents an alert then waits for dismiss', async () => {
+      const overlay = fakeOverlay();
+      const { controller, alertCtrl } = setup({ alertOverlay: overlay });
+      await controller.alertClose({ header: 'Info', message: 'Done' });
+      expect(alertCtrl.create).toHaveBeenCalledOnce();
+      expect(overlay.present).toHaveBeenCalledOnce();
+      expect(overlay.onWillDismiss).toHaveBeenCalledOnce();
+    });
+
+    it('uses the injected close label for the button', async () => {
+      const { controller, alertCtrl } = setup();
+      await controller.alertClose({ header: 'H', message: 'M' });
+      const createArgs = alertCtrl.create.mock.calls[0][0];
+      expect(createArgs.buttons).toContain(TEST_LABELS.close);
+    });
+  });
+
+  // ---- presentToast ---------------------------------------------------------
+  describe('presentToast', () => {
+    it('applies kit defaults (position=top, duration=2000) and presents the toast', async () => {
+      const overlay = fakeOverlay();
+      const { controller, toastCtrl } = setup({ toastOverlay: overlay });
+      await controller.presentToast({ message: 'Hello' });
+      const createArgs = toastCtrl.create.mock.calls[0][0];
+      expect(createArgs.position).toBe('top');
+      expect(createArgs.duration).toBe(2000);
+      expect(overlay.present).toHaveBeenCalledOnce();
+    });
+
+    it('caller options override kit defaults', async () => {
+      const { controller, toastCtrl } = setup();
+      await controller.presentToast({ message: 'Hi', position: 'bottom', duration: 5000 });
+      const createArgs = toastCtrl.create.mock.calls[0][0];
+      expect(createArgs.position).toBe('bottom');
+      expect(createArgs.duration).toBe(5000);
+    });
+
+    it('includes the close label button from config', async () => {
+      const { controller, toastCtrl } = setup();
+      await controller.presentToast({ message: 'Test' });
+      const createArgs = toastCtrl.create.mock.calls[0][0];
+      expect(createArgs.buttons).toContain(TEST_LABELS.close);
+    });
+
+    it('returns the toast element', async () => {
+      const overlay = fakeOverlay();
+      const { controller, toastCtrl } = setup({ toastOverlay: overlay });
+      toastCtrl.create.mockResolvedValue(overlay);
+      const result = await controller.presentToast({ message: 'Test' });
+      expect(result).toBe(overlay);
+    });
+  });
+
+  // ---- presentModal ---------------------------------------------------------
+  describe('presentModal', () => {
+    class FakeComponent {}
+
+    it('creates the modal with the given component and props', async () => {
+      const { controller, modalCtrl } = setup({ modalOverlay: fakeOverlay(undefined, { result: 42 }) });
+      await controller.presentModal(FakeComponent, { id: 1 });
+      const createArgs = modalCtrl.create.mock.calls[0][0];
+      expect(createArgs.component).toBe(FakeComponent);
+      expect(createArgs.componentProps).toEqual({ id: 1 });
+    });
+
+    it('returns the dismiss data', async () => {
+      const dismissData = { selected: 'foo' };
+      const { controller } = setup({ modalOverlay: fakeOverlay(undefined, dismissData) });
+      const result = await controller.presentModal<{ selected: string }>(FakeComponent);
+      expect(result).toEqual(dismissData);
+    });
+
+    it('presents the modal', async () => {
+      const overlay = fakeOverlay(undefined, null);
+      const { controller } = setup({ modalOverlay: overlay });
+      await controller.presentModal(FakeComponent);
+      expect(overlay.present).toHaveBeenCalledOnce();
+    });
+
+    it('waits for onDidDismiss before returning', async () => {
+      const overlay = fakeOverlay(undefined, 'done');
+      const { controller } = setup({ modalOverlay: overlay });
+      await controller.presentModal(FakeComponent);
+      expect(overlay.onDidDismiss).toHaveBeenCalledOnce();
+    });
+  });
+
+  // ---- provideKitOverlay / KIT_OVERLAY_CONFIG -------------------------------
+  describe('provideKitOverlay', () => {
+    it('injects the configured labels', () => {
+      TestBed.resetTestingModule();
+      TestBed.configureTestingModule({
+        providers: [provideZonelessChangeDetection(), provideKitOverlay({ labels: { close: 'Fermer', cancel: 'Annuler' } })],
+      });
+      const cfg = TestBed.inject(KIT_OVERLAY_CONFIG);
+      expect(cfg.labels.close).toBe('Fermer');
+      expect(cfg.labels.cancel).toBe('Annuler');
+    });
+  });
+});

package/src/lib/overlay/kit-overlay.controller.ts

@@ -0,0 +1,206 @@
+import { inject, Injectable } from '@angular/core';
+import type { ModalOptions, ToastOptions } from '@ionic/angular/standalone';
+import { AlertController, ModalController, ToastController } from '@ionic/angular/standalone';
+import type { PluginListenerHandle } from '@capacitor/core';
+import { Capacitor } from '@capacitor/core';
+import { Keyboard } from '@capacitor/keyboard';
+import { KIT_OVERLAY_CONFIG } from './overlay-config';
+import { kitImpact } from '../utils/haptics';
+
+/**
+ * Options for {@link KitOverlayController.presentModal}.
+ *
+ * @remarks
+ * Extends Ionic's `ModalOptions` but omits `component` and `componentProps`, which are passed as
+ * dedicated arguments instead.
+ */
+export 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}.
+ */
+export 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.
+ */
+export 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;
+}
+
+/**
+ * Attach a native keyboard listener that grows the modal to its maximum breakpoint when the
+ * keyboard appears.
+ *
+ * @param modal - the presented modal element to resize
+ * @returns a listener handle; on non-native platforms a no-op handle whose `remove()` does nothing
+ * @internal
+ */
+const watchModalKeyboard = async (modal: HTMLIonModalElement): Promise<PluginListenerHandle> => {
+  if (!Capacitor.isNativePlatform()) {
+    return { remove: async () => undefined };
+  }
+  return Keyboard.addListener('keyboardDidShow', () => modal.setCurrentBreakpoint(1));
+};
+
+/**
+ * Ergonomic wrapper that consolidates Ionic's overlay controllers (Modal / Toast / Alert).
+ *
+ * @remarks
+ * Folds the repetitive create → present → onDidDismiss sequence into single calls and returns the
+ * relevant result directly. It holds no application-specific policy such as navigation; compose
+ * those concerns on the consuming side.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly overlay: KitOverlayController) {}
+ *
+ * async edit(): Promise<void> {
+ *   const result = await this.overlay.presentModal<EditResult>(EditPage, { id: 1 });
+ *   if (result) {
+ *     await this.overlay.presentToast({ message: 'Saved' });
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class KitOverlayController {
+  readonly #modalCtrl = inject(ModalController);
+  readonly #toastCtrl = inject(ToastController);
+  readonly #alertCtrl = inject(AlertController);
+  readonly #labels = inject(KIT_OVERLAY_CONFIG).labels;
+
+  /**
+   * Present a modal and resolve with the data passed to its dismissal.
+   *
+   * @typeParam O - type of the data returned when the modal is dismissed
+   * @param component - the component to render inside the modal
+   * @param componentProps - props to pass to the modal component
+   * @param options - additional modal options, including {@link KitModalPresentOptions.watchKeyboard}
+   * @returns the dismiss data, or `undefined` when the modal is dismissed without data
+   * @example
+   * ```ts
+   * const data = await overlay.presentModal<{ saved: boolean }>(EditPage, { id: 1 }, { watchKeyboard: true });
+   * ```
+   */
+  async presentModal<O = unknown>(
+    component: ModalOptions['component'],
+    componentProps?: ModalOptions['componentProps'],
+    options: KitModalPresentOptions = {},
+  ): Promise<O | undefined> {
+    const { watchKeyboard, ...modalOptions } = options;
+    const modal = await this.#modalCtrl.create({ component, componentProps, ...modalOptions });
+    await modal.present();
+    const handle = watchKeyboard ? await watchModalKeyboard(modal) : null;
+    const { data } = await modal.onDidDismiss<O>();
+    await handle?.remove();
+    return data;
+  }
+
+  /**
+   * Present a toast using kit defaults that the caller may override.
+   *
+   * @remarks
+   * Defaults to a top position, a 2000ms duration, a vertical swipe gesture, and a close button
+   * from the configured labels; any of these can be overridden via `options`. Presenting a toast
+   * also triggers light native haptic feedback as an intentional kit UX choice.
+   *
+   * @param options - Ionic toast options that override the kit defaults
+   * @returns the presented toast element
+   * @example
+   * ```ts
+   * await overlay.presentToast({ message: 'Copied to clipboard' });
+   * ```
+   */
+  async presentToast(options: ToastOptions): Promise<HTMLIonToastElement> {
+    void kitImpact();
+    const toast = await this.#toastCtrl.create({
+      position: 'top',
+      duration: 2000,
+      buttons: [this.#labels.close],
+      swipeGesture: 'vertical',
+      ...options,
+    });
+    await toast.present();
+    return toast;
+  }
+
+  /**
+   * Present a notification alert with a single "close" button and wait for it to be dismissed.
+   *
+   * @param options - alert content (header, message, optional sub-header)
+   * @returns a Promise that resolves once the alert has been dismissed
+   * @example
+   * ```ts
+   * await overlay.alertClose({ header: 'Done', message: 'Your changes were saved.' });
+   * ```
+   */
+  async alertClose(options: KitAlertCloseOptions): Promise<void> {
+    const alert = await this.#alertCtrl.create({
+      header: options.header,
+      subHeader: options.subHeader,
+      message: options.message,
+      buttons: [this.#labels.close],
+    });
+    await alert.present();
+    await alert.onWillDismiss();
+  }
+
+  /**
+   * Present a confirmation alert with cancel and OK buttons.
+   *
+   * @param options - alert content plus the OK button text via {@link KitAlertConfirmOptions.okText}
+   * @returns `true` when the user presses OK, `false` otherwise (cancel or backdrop dismissal)
+   * @example
+   * ```ts
+   * const ok = await overlay.alertConfirm({
+   *   header: 'Delete item?',
+   *   message: 'This cannot be undone.',
+   *   okText: 'Delete',
+   * });
+   * if (ok) {
+   *   await remove();
+   * }
+   * ```
+   */
+  async alertConfirm(options: KitAlertConfirmOptions): Promise<boolean> {
+    const alert = await this.#alertCtrl.create({
+      header: options.header,
+      subHeader: options.subHeader,
+      message: options.message,
+      buttons: [
+        { text: this.#labels.cancel, role: 'cancel' },
+        { text: options.okText, role: 'confirm' },
+      ],
+    });
+    await alert.present();
+    const { role } = await alert.onWillDismiss();
+    return role === 'confirm';
+  }
+}

package/src/lib/overlay/kit-reload-alert.controller.spec.ts

@@ -0,0 +1,105 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { AlertController } from '@ionic/angular/standalone';
+
+import { KitReloadAlertController } from './kit-reload-alert.controller';
+import { provideKitOverlay } from './overlay-config';
+
+const TEST_LABELS = { close: 'Close', cancel: 'Cancel' };
+const OPTS = { header: 'Network error', message: 'Reload? (0)', okText: 'Reload' };
+
+function fakeAlert() {
+  let dismissResolve: () => void = () => undefined;
+  return {
+    present: vi.fn().mockResolvedValue(undefined),
+    dismiss: vi.fn().mockResolvedValue(undefined),
+    // onDidDismiss resolves when we trigger it, mirroring Ionic's lifecycle.
+    onDidDismiss: vi.fn().mockReturnValue(new Promise<void>((r) => (dismissResolve = r))),
+    triggerDismiss: () => dismissResolve(),
+  };
+}
+
+function setup(alert = fakeAlert()) {
+  const alertCtrl = { create: vi.fn().mockResolvedValue(alert) };
+  TestBed.configureTestingModule({
+    providers: [
+      provideZonelessChangeDetection(),
+      KitReloadAlertController,
+      provideKitOverlay({ labels: TEST_LABELS }),
+      { provide: AlertController, useValue: alertCtrl },
+    ],
+  });
+  return { controller: TestBed.inject(KitReloadAlertController), alertCtrl, alert };
+}
+
+describe('KitReloadAlertController', () => {
+  let reload: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    reload = vi.fn();
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: { ...window.location, reload },
+    });
+    document.body.innerHTML = '';
+  });
+
+  afterEach(() => {
+    TestBed.resetTestingModule();
+  });
+
+  it('presents with backdrop lock and a cancel(role)/reload button pair', async () => {
+    const { controller, alertCtrl } = setup();
+    await controller.present(OPTS);
+    const args = alertCtrl.create.mock.calls[0][0];
+    expect(args.backdropDismiss).toBe(false);
+    expect(args.buttons[0]).toMatchObject({ text: 'Cancel', role: 'cancel' });
+    expect(args.buttons[1].text).toBe('Reload');
+  });
+
+  it('reloads the page from the confirm button handler', async () => {
+    const { controller, alertCtrl } = setup();
+    await controller.present(OPTS);
+    const args = alertCtrl.create.mock.calls[0][0];
+    args.buttons[1].handler();
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it('de-dups: a second present while showing is a no-op', async () => {
+    const { controller, alertCtrl } = setup();
+    await controller.present(OPTS);
+    await controller.present(OPTS);
+    expect(alertCtrl.create).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not present when an ion-alert already exists in the DOM', async () => {
+    document.body.appendChild(document.createElement('ion-alert'));
+    const { controller, alertCtrl } = setup();
+    await controller.present(OPTS);
+    expect(alertCtrl.create).not.toHaveBeenCalled();
+  });
+
+  it('dismiss() dismisses the tracked alert (auto-dismiss on reconnect)', async () => {
+    const { controller, alert } = setup();
+    await controller.present(OPTS);
+    await controller.dismiss();
+    expect(alert.dismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('dismiss() is a no-op when nothing is showing', async () => {
+    const { controller, alert } = setup();
+    await controller.dismiss();
+    expect(alert.dismiss).not.toHaveBeenCalled();
+  });
+
+  it('allows presenting again after the alert is dismissed', async () => {
+    const first = fakeAlert();
+    const { controller, alertCtrl } = setup(first);
+    await controller.present(OPTS);
+    await controller.dismiss();
+    first.triggerDismiss();
+    await Promise.resolve();
+    await controller.present(OPTS);
+    expect(alertCtrl.create).toHaveBeenCalledTimes(2);
+  });
+});

package/src/lib/overlay/kit-reload-alert.controller.ts

@@ -0,0 +1,108 @@
+import { inject, Injectable } from '@angular/core';
+import { AlertController } from '@ionic/angular/standalone';
+import { KIT_OVERLAY_CONFIG } from './overlay-config';
+
+/**
+ * Content for {@link KitReloadAlertController.present}.
+ */
+export 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();
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class KitReloadAlertController {
+  readonly #alertCtrl = inject(AlertController);
+  readonly #labels = inject(KIT_OVERLAY_CONFIG).labels;
+  #alert: HTMLIonAlertElement | null = null;
+
+  /**
+   * Present the reload alert, unless one is already on screen.
+   *
+   * @param options - alert content plus the reload-button text
+   * @returns a Promise that resolves once the alert has been presented (or immediately if suppressed)
+   */
+  async present(options: KitReloadAlertOptions): Promise<void> {
+    // この controller 経由でも直書き ion-alert でも、多重表示しない。
+    if (this.#alert || document.querySelector('ion-alert')) {
+      return;
+    }
+    const alert = await this.#alertCtrl.create({
+      header: options.header,
+      message: options.message,
+      backdropDismiss: false,
+      buttons: [
+        { text: this.#labels.cancel, role: 'cancel' },
+        {
+          text: options.okText,
+          handler: () => {
+            location.reload();
+          },
+        },
+      ],
+    });
+    this.#alert = alert;
+    void alert.onDidDismiss().then(() => {
+      // 別の present で置き換わっていない限り、追跡を解除する。
+      if (this.#alert === alert) {
+        this.#alert = null;
+      }
+    });
+    await alert.present();
+  }
+
+  /**
+   * Dismiss the tracked reload alert if one is showing.
+   *
+   * @remarks
+   * Typically called from a later successful response so a stale "network error" alert clears once
+   * connectivity is restored. A no-op when nothing is showing.
+   *
+   * @returns a Promise that resolves once the alert has been dismissed (or immediately if none)
+   */
+  async dismiss(): Promise<void> {
+    const alert = this.#alert;
+    this.#alert = null;
+    await alert?.dismiss();
+  }
+}