@nextclaw/ui 0.12.8 → 0.12.10

package/src/pwa/components/pwa-install-entry.test.tsx

@@ -0,0 +1,110 @@
+import { render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { PwaInstallBanner, PwaInstallCard, PwaUpdateBanner } from '@/pwa/components/pwa-install-entry';
+import { usePwaStore, createInitialPwaState } from '@/pwa/stores/pwa.store';
+
+describe('PwaInstallCard', () => {
+  beforeEach(() => {
+    usePwaStore.setState(createInitialPwaState());
+  });
+
+  it('renders install action when prompt install is available', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'available',
+      installMethod: 'prompt',
+      blockedReason: null,
+      dismissedInstallPrompt: false,
+      updateAvailable: false,
+      registrationFailed: false
+    });
+
+    render(<PwaInstallCard />);
+
+    expect(screen.getByRole('button', { name: 'Install NextClaw' })).toBeTruthy();
+    expect(screen.getByText('Installable')).toBeTruthy();
+  });
+
+  it('renders desktop host description when suppressed', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'suppressed',
+      installMethod: 'none',
+      blockedReason: 'desktop-host',
+      dismissedInstallPrompt: false,
+      updateAvailable: false,
+      registrationFailed: false
+    });
+
+    render(<PwaInstallCard />);
+
+    expect(screen.getByText('Desktop Host Active')).toBeTruthy();
+    expect(screen.getByText(/already running inside the Electron desktop host/i)).toBeTruthy();
+  });
+
+  it('does not render update banner before installation', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'available',
+      installMethod: 'manual',
+      blockedReason: null,
+      dismissedInstallPrompt: false,
+      updateAvailable: true,
+      registrationFailed: false
+    });
+
+    const { container } = render(<PwaUpdateBanner />);
+
+    expect(container.textContent).toBe('');
+  });
+
+  it('renders update banner only for installed pwa', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'installed',
+      installMethod: 'none',
+      blockedReason: null,
+      dismissedInstallPrompt: false,
+      updateAvailable: true,
+      registrationFailed: false
+    });
+
+    render(<PwaUpdateBanner />);
+
+    expect(screen.getByText('NextClaw Update Ready')).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Refresh Now' })).toBeTruthy();
+  });
+
+  it('renders install banner when prompt install is available and not dismissed', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'available',
+      installMethod: 'prompt',
+      blockedReason: null,
+      dismissedInstallPrompt: false,
+      updateAvailable: false,
+      registrationFailed: false
+    });
+
+    render(<PwaInstallBanner />);
+
+    expect(screen.getByText('Pin NextClaw as an App')).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Install NextClaw' })).toBeTruthy();
+  });
+
+  it('does not render install banner after dismissal', () => {
+    usePwaStore.setState({
+      initialized: true,
+      installability: 'available',
+      installMethod: 'prompt',
+      blockedReason: null,
+      dismissedInstallPrompt: true,
+      updateAvailable: false,
+      registrationFailed: false
+    });
+
+    const { container } = render(<PwaInstallBanner />);
+
+    expect(container.textContent).toBe('');
+  });
+});

package/src/pwa/components/pwa-install-entry.tsx

@@ -0,0 +1,205 @@
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { usePwaStore } from '@/pwa/stores/pwa.store';
+import { pwaInstallManager } from '@/pwa/managers/pwa-install.manager';
+import { pwaRuntimeManager } from '@/pwa/managers/pwa-runtime.manager';
+import { t } from '@/lib/i18n';
+import { cn } from '@/lib/utils';
+import { Download, RefreshCw, Smartphone, X } from 'lucide-react';
+
+function InstallStatusBadge() {
+  const installability = usePwaStore((state) => state.installability);
+
+  const badgeClassName =
+    installability === 'installed'
+      ? 'bg-emerald-50 text-emerald-700 border-emerald-200'
+      : installability === 'available'
+        ? 'bg-amber-50 text-amber-700 border-amber-200'
+        : 'bg-gray-100 text-gray-600 border-gray-200';
+
+  return (
+    <span className={cn('inline-flex items-center rounded-full border px-3 py-1 text-xs font-medium', badgeClassName)}>
+      {resolveInstallabilityLabel(installability)}
+    </span>
+  );
+}
+
+function resolveInstallabilityLabel(installability: string): string {
+  if (installability === 'available') {
+    return t('pwaInstallStatusAvailable');
+  }
+  if (installability === 'installed') {
+    return t('pwaInstallStatusInstalled');
+  }
+  if (installability === 'suppressed') {
+    return t('pwaInstallStatusDesktopHost');
+  }
+  return t('pwaInstallStatusUnavailable');
+}
+
+function resolveCardDescription(
+  installability: string,
+  installMethod: string,
+  blockedReason: string | null
+) {
+  if (installability === 'installed') {
+    return t('pwaInstallCardInstalled');
+  }
+
+  if (installability === 'suppressed') {
+    return t('pwaInstallCardSuppressed');
+  }
+
+  if (installability === 'available' && installMethod === 'prompt') {
+    return t('pwaInstallCardPrompt');
+  }
+
+  if (installability === 'available') {
+    return t('pwaInstallCardManual');
+  }
+
+  if (blockedReason === 'insecure-context') {
+    return t('pwaInstallCardInsecureContext');
+  }
+
+  if (blockedReason === 'dev-server') {
+    return t('pwaInstallCardDevServer');
+  }
+
+  return t('pwaInstallCardUnsupported');
+}
+
+export function PwaInstallCard() {
+  const installability = usePwaStore((state) => state.installability);
+  const installMethod = usePwaStore((state) => state.installMethod);
+  const blockedReason = usePwaStore((state) => state.blockedReason);
+
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-start justify-between gap-4 space-y-0">
+        <div className="space-y-2">
+          <CardTitle>{t('pwaInstallTitle')}</CardTitle>
+          <CardDescription>{t('pwaInstallDescription')}</CardDescription>
+        </div>
+        <InstallStatusBadge />
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="rounded-2xl border border-gray-200 bg-gray-50/90 p-4">
+          <p className="text-sm leading-6 text-gray-700">
+            {resolveCardDescription(installability, installMethod, blockedReason)}
+          </p>
+        </div>
+
+        {installability === 'available' && installMethod === 'prompt' ? (
+          <div className="flex flex-wrap items-center gap-3">
+            <Button
+              type="button"
+              className="gap-2"
+              onClick={() => {
+                void pwaInstallManager.promptInstall();
+              }}
+            >
+              <Download className="h-4 w-4" />
+              {t('pwaInstallAction')}
+            </Button>
+            <p className="text-sm text-gray-500">{t('pwaInstallPromptHint')}</p>
+          </div>
+        ) : null}
+
+        {installability === 'available' && installMethod === 'manual' ? (
+          <div className="flex items-start gap-3 rounded-2xl border border-dashed border-gray-300 bg-white p-4">
+            <Smartphone className="mt-0.5 h-4 w-4 text-gray-500" />
+            <p className="text-sm leading-6 text-gray-600">{t('pwaInstallManualHint')}</p>
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+export function PwaInstallBanner() {
+  const installability = usePwaStore((state) => state.installability);
+  const installMethod = usePwaStore((state) => state.installMethod);
+  const dismissedInstallPrompt = usePwaStore((state) => state.dismissedInstallPrompt);
+
+  if (installability !== 'available' || installMethod !== 'prompt' || dismissedInstallPrompt) {
+    return null;
+  }
+
+  return (
+    <div className="fixed bottom-5 right-5 z-50 w-[min(420px,calc(100vw-2rem))] rounded-[26px] border border-gray-200 bg-white/95 p-5 shadow-2xl backdrop-blur-xl">
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1">
+          <p className="text-sm font-semibold text-gray-900">{t('pwaInstallBannerTitle')}</p>
+          <p className="text-sm leading-6 text-gray-600">{t('pwaInstallBannerDescription')}</p>
+        </div>
+        <button
+          type="button"
+          aria-label={t('pwaInstallDismiss')}
+          className="rounded-full p-1 text-gray-400 transition hover:bg-gray-100 hover:text-gray-600"
+          onClick={() => {
+            pwaInstallManager.dismissInstallPrompt();
+          }}
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+      <div className="mt-4 flex items-center gap-3">
+        <Button
+          type="button"
+          size="sm"
+          className="gap-2"
+          onClick={() => {
+            void pwaInstallManager.promptInstall();
+          }}
+        >
+          <Download className="h-4 w-4" />
+          {t('pwaInstallAction')}
+        </Button>
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          onClick={() => {
+            pwaInstallManager.dismissInstallPrompt();
+          }}
+        >
+          {t('pwaInstallDismiss')}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export function PwaUpdateBanner() {
+  const updateAvailable = usePwaStore((state) => state.updateAvailable);
+  const installability = usePwaStore((state) => state.installability);
+
+  if (!updateAvailable || installability !== 'installed') {
+    return null;
+  }
+
+  return (
+    <div className="fixed top-5 right-5 z-50 w-[min(420px,calc(100vw-2rem))] rounded-[26px] border border-gray-200 bg-white/95 p-5 shadow-2xl backdrop-blur-xl">
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1">
+          <p className="text-sm font-semibold text-gray-900">{t('pwaUpdateBannerTitle')}</p>
+          <p className="text-sm leading-6 text-gray-600">{t('pwaUpdateBannerDescription')}</p>
+        </div>
+      </div>
+      <div className="mt-4">
+        <Button
+          type="button"
+          size="sm"
+          className="gap-2"
+          onClick={() => {
+            void pwaRuntimeManager.applyUpdate();
+          }}
+        >
+          <RefreshCw className="h-4 w-4" />
+          {t('pwaUpdateAction')}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/pwa/managers/pwa-install.manager.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PwaInstallManager } from '@/pwa/managers/pwa-install.manager';
+import {
+  PWA_INSTALL_BANNER_DISMISS_STORAGE_KEY,
+  PWA_INSTALL_BANNER_LEGACY_UNTIL_STORAGE_KEY
+} from '@/pwa/pwa-install-banner.storage';
+import { usePwaStore, createInitialPwaState } from '@/pwa/stores/pwa.store';
+
+function createMatchMedia(matches = false): typeof window.matchMedia {
+  return vi.fn().mockImplementation(() => ({
+    matches,
+    media: '(display-mode: standalone)',
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn()
+  }));
+}
+
+function createBeforeInstallPromptEvent(outcome: 'accepted' | 'dismissed' = 'accepted'): BeforeInstallPromptEvent {
+  const event = new Event('beforeinstallprompt') as BeforeInstallPromptEvent;
+  event.preventDefault = vi.fn();
+  event.prompt = vi.fn();
+  event.userChoice = Promise.resolve({ outcome, platform: 'web' });
+  return event;
+}
+
+describe('PwaInstallManager', () => {
+  let manager: PwaInstallManager;
+
+  beforeEach(() => {
+    manager = new PwaInstallManager();
+    usePwaStore.setState(createInitialPwaState());
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: createMatchMedia(false)
+    });
+    Object.defineProperty(window, 'isSecureContext', {
+      configurable: true,
+      value: true
+    });
+    Object.defineProperty(window, 'nextclawDesktop', {
+      configurable: true,
+      value: undefined
+    });
+    Object.defineProperty(navigator, 'serviceWorker', {
+      configurable: true,
+      value: {}
+    });
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    manager.resetForTests();
+    window.localStorage.clear();
+  });
+
+  it('marks desktop host as suppressed', () => {
+    Object.defineProperty(window, 'nextclawDesktop', {
+      configurable: true,
+      value: {}
+    });
+
+    manager.start();
+
+    const state = usePwaStore.getState();
+    expect(state.installability).toBe('suppressed');
+    expect(state.blockedReason).toBe('desktop-host');
+  });
+
+  it('marks installed when display mode is standalone', () => {
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: createMatchMedia(true)
+    });
+
+    manager.start();
+
+    const state = usePwaStore.getState();
+    expect(state.installability).toBe('installed');
+    expect(state.installMethod).toBe('none');
+  });
+
+  it('falls back to manual install when prompt event is unavailable', () => {
+    manager.start();
+
+    const state = usePwaStore.getState();
+    expect(state.installability).toBe('available');
+    expect(state.installMethod).toBe('manual');
+  });
+
+  it('marks insecure non-local origins as unsupported', () => {
+    Object.defineProperty(window, 'isSecureContext', {
+      configurable: true,
+      value: false
+    });
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: new URL('http://192.168.1.7:5174')
+    });
+
+    manager.start();
+
+    const state = usePwaStore.getState();
+    expect(state.installability).toBe('unsupported');
+    expect(state.blockedReason).toBe('insecure-context');
+  });
+
+  it('keeps install banner dismissed after beforeinstallprompt fires again', () => {
+    manager.start();
+    window.dispatchEvent(createBeforeInstallPromptEvent());
+
+    manager.dismissInstallPrompt();
+    expect(usePwaStore.getState().dismissedInstallPrompt).toBe(true);
+
+    window.dispatchEvent(createBeforeInstallPromptEvent());
+
+    expect(usePwaStore.getState().dismissedInstallPrompt).toBe(true);
+    expect(window.localStorage.getItem(PWA_INSTALL_BANNER_DISMISS_STORAGE_KEY)).toBeTruthy();
+  });
+
+  it('keeps install banner dismissed after user dismisses the native install prompt', async () => {
+    manager.start();
+    const promptEvent = createBeforeInstallPromptEvent('dismissed');
+    window.dispatchEvent(promptEvent);
+
+    const outcome = await manager.promptInstall();
+
+    expect(outcome).toBe('dismissed');
+    expect(promptEvent.prompt).toHaveBeenCalledTimes(1);
+    expect(usePwaStore.getState().dismissedInstallPrompt).toBe(true);
+    expect(window.localStorage.getItem(PWA_INSTALL_BANNER_DISMISS_STORAGE_KEY)).toBe('1');
+  });
+
+  it('hydrates dismissed state from persisted dismiss flag on fresh store init', () => {
+    window.localStorage.setItem(
+      PWA_INSTALL_BANNER_DISMISS_STORAGE_KEY,
+      '1'
+    );
+
+    usePwaStore.setState(createInitialPwaState());
+
+    expect(usePwaStore.getState().dismissedInstallPrompt).toBe(true);
+  });
+
+  it('migrates legacy snooze timestamps into the permanent dismiss flag', () => {
+    window.localStorage.setItem(
+      PWA_INSTALL_BANNER_LEGACY_UNTIL_STORAGE_KEY,
+      String(Date.now() + 60_000)
+    );
+
+    usePwaStore.setState(createInitialPwaState());
+
+    expect(usePwaStore.getState().dismissedInstallPrompt).toBe(true);
+    expect(window.localStorage.getItem(PWA_INSTALL_BANNER_DISMISS_STORAGE_KEY)).toBe('1');
+    expect(window.localStorage.getItem(PWA_INSTALL_BANNER_LEGACY_UNTIL_STORAGE_KEY)).toBeNull();
+  });
+});

package/src/pwa/managers/pwa-install.manager.ts

@@ -0,0 +1,232 @@
+import { usePwaStore, createInitialPwaState } from '@/pwa/stores/pwa.store';
+import type { PwaInstallBlockedReason, PwaInstallMethod, PwaInstallPromptOutcome, PwaInstallabilityState } from '@/pwa/pwa.types';
+import { pwaRuntimeManager } from '@/pwa/managers/pwa-runtime.manager';
+import {
+  clearPwaInstallBannerDismissal,
+  dismissPwaInstallBanner,
+  isPwaInstallBannerDismissed
+} from '@/pwa/pwa-install-banner.storage';
+import { t } from '@/lib/i18n';
+import { toast } from 'sonner';
+
+type InstallabilityResolution = {
+  installability: PwaInstallabilityState;
+  installMethod: PwaInstallMethod;
+  blockedReason: PwaInstallBlockedReason;
+};
+
+export class PwaInstallManager {
+  private started = false;
+  private deferredPrompt: BeforeInstallPromptEvent | null = null;
+  private displayModeMediaQuery: MediaQueryList | null = null;
+
+  start = () => {
+    if (this.started || typeof window === 'undefined') {
+      return;
+    }
+
+    this.started = true;
+    window.addEventListener('beforeinstallprompt', this.handleBeforeInstallPrompt as EventListener);
+    window.addEventListener('appinstalled', this.handleAppInstalled);
+
+    if (typeof window.matchMedia === 'function') {
+      this.displayModeMediaQuery = window.matchMedia('(display-mode: standalone)');
+      this.bindDisplayModeListener(this.displayModeMediaQuery, this.handleDisplayModeChanged);
+    }
+
+    this.refreshState();
+  };
+
+  stop = () => {
+    if (!this.started || typeof window === 'undefined') {
+      return;
+    }
+
+    window.removeEventListener('beforeinstallprompt', this.handleBeforeInstallPrompt as EventListener);
+    window.removeEventListener('appinstalled', this.handleAppInstalled);
+    if (this.displayModeMediaQuery) {
+      this.unbindDisplayModeListener(this.displayModeMediaQuery, this.handleDisplayModeChanged);
+      this.displayModeMediaQuery = null;
+    }
+
+    this.deferredPrompt = null;
+    this.started = false;
+  };
+
+  resetForTests = () => {
+    this.stop();
+    usePwaStore.setState(createInitialPwaState());
+  };
+
+  refreshState = () => {
+    const resolution = this.resolveInstallability();
+    usePwaStore.setState((state) => ({
+      ...state,
+      initialized: true,
+      installability: resolution.installability,
+      installMethod: resolution.installMethod,
+      blockedReason: resolution.blockedReason,
+      dismissedInstallPrompt: isPwaInstallBannerDismissed()
+    }));
+    void pwaRuntimeManager.syncUpdateAvailability();
+  };
+
+  dismissInstallPrompt = () => {
+    dismissPwaInstallBanner();
+    usePwaStore.setState({
+      dismissedInstallPrompt: true
+    });
+  };
+
+  promptInstall = async (): Promise<PwaInstallPromptOutcome> => {
+    const resolution = this.resolveInstallability();
+    if (resolution.installability !== 'available') {
+      return 'unavailable';
+    }
+
+    if (resolution.installMethod === 'manual' || !this.deferredPrompt) {
+      return 'manual';
+    }
+
+    this.deferredPrompt.prompt();
+    const result = await this.deferredPrompt.userChoice;
+    this.deferredPrompt = null;
+    if (result.outcome === 'accepted') {
+      clearPwaInstallBannerDismissal();
+      this.refreshState();
+      toast.success(t('pwaInstallAccepted'));
+      return 'accepted';
+    }
+
+    this.dismissInstallPrompt();
+    this.refreshState();
+    return 'dismissed';
+  };
+
+  private handleBeforeInstallPrompt = (event: BeforeInstallPromptEvent) => {
+    event.preventDefault();
+    this.deferredPrompt = event;
+    this.refreshState();
+  };
+
+  private handleAppInstalled = () => {
+    this.deferredPrompt = null;
+    clearPwaInstallBannerDismissal();
+    usePwaStore.setState({
+      dismissedInstallPrompt: true
+    });
+    toast.success(t('pwaInstalledToast'));
+    this.refreshState();
+  };
+
+  private handleDisplayModeChanged = () => {
+    this.refreshState();
+  };
+
+  private resolveInstallability = (): InstallabilityResolution => {
+    if (this.isDevelopmentServer()) {
+      return {
+        installability: 'unsupported',
+        installMethod: 'none',
+        blockedReason: 'dev-server'
+      };
+    }
+
+    if (this.hasDesktopHost()) {
+      return {
+        installability: 'suppressed',
+        installMethod: 'none',
+        blockedReason: 'desktop-host'
+      };
+    }
+
+    if (this.isStandalone()) {
+      return {
+        installability: 'installed',
+        installMethod: 'none',
+        blockedReason: null
+      };
+    }
+
+    if (!this.hasInstallSurfaceSupport()) {
+      return {
+        installability: 'unsupported',
+        installMethod: 'none',
+        blockedReason: 'missing-browser-support'
+      };
+    }
+
+    if (!this.isEligibleInstallContext()) {
+      return {
+        installability: 'unsupported',
+        installMethod: 'none',
+        blockedReason: 'insecure-context'
+      };
+    }
+
+    return {
+      installability: 'available',
+      installMethod: this.deferredPrompt ? 'prompt' : 'manual',
+      blockedReason: null
+    };
+  };
+
+  private hasDesktopHost = (): boolean => {
+    return typeof window !== 'undefined' && Boolean(window.nextclawDesktop);
+  };
+
+  private hasInstallSurfaceSupport = (): boolean => {
+    return typeof window !== 'undefined' && typeof window.matchMedia === 'function' && 'serviceWorker' in navigator;
+  };
+
+  private isEligibleInstallContext = (): boolean => {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+    return window.isSecureContext || this.isTrustedLocalhost(window.location.hostname);
+  };
+
+  private isTrustedLocalhost = (hostname: string): boolean => {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+  };
+
+  private isDevelopmentServer = (): boolean => {
+    return typeof window !== 'undefined' && import.meta.env.DEV && !import.meta.env.VITEST;
+  };
+
+  private isStandalone = (): boolean => {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const navigatorWithStandalone = window.navigator as Navigator & { standalone?: boolean };
+    const matchesStandalone =
+      typeof window.matchMedia === 'function' && window.matchMedia('(display-mode: standalone)').matches;
+    return matchesStandalone || navigatorWithStandalone.standalone === true;
+  };
+
+  private bindDisplayModeListener = (query: MediaQueryList, listener: () => void) => {
+    if ('addEventListener' in query) {
+      query.addEventListener('change', listener);
+      return;
+    }
+    const legacyQuery = query as MediaQueryList & {
+      addListener?: (callback: (event: MediaQueryListEvent) => void) => void;
+    };
+    legacyQuery.addListener?.(listener);
+  };
+
+  private unbindDisplayModeListener = (query: MediaQueryList, listener: () => void) => {
+    if ('removeEventListener' in query) {
+      query.removeEventListener('change', listener);
+      return;
+    }
+    const legacyQuery = query as MediaQueryList & {
+      removeListener?: (callback: (event: MediaQueryListEvent) => void) => void;
+    };
+    legacyQuery.removeListener?.(listener);
+  };
+
+}
+
+export const pwaInstallManager = new PwaInstallManager();