@swoff/cli 0.3.13 → 0.3.14

package/templates/react/useMutation.tsx

@@ -4,7 +4,7 @@ import {
   trackMutation,
   resolveMutation,
   rejectMutation,
-} from "../offline/state.ts";
+} from "../mutation/state.ts";
 import type { FetchWithCacheOptions } from "../fetch/core.ts";
 
 export interface MutateCallbacks<TData> {
@@ -25,6 +25,12 @@ export interface UseMutationOptions<TData> extends FetchWithCacheOptions {
   retry?: number | boolean;
 }
 
+export type MutateResult<T> =
+  | { status: "skipped" }
+  | { status: "queued" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+
 /**
  * Hook for mutations (POST, PUT, PATCH, DELETE) with auto-invalidation, offline queuing,
  * optimistic updates, and dual-level callbacks.
@@ -44,28 +50,24 @@ export interface UseMutationOptions<TData> extends FetchWithCacheOptions {
  *   // Optimistic update with rollback:
  *   const { mutate } = useMutation("/api/todos", {
  *     method: "POST",
- *     onMutate: () => { /* set optimistic state *\/ },
- *     onError: () => { /* rollback *\/ },
+ *     onMutate: () => { /* set optimistic state *\\/ },
+ *     onError: () => { /* rollback *\\/ },
  *   });
+ *
+ *   // Check result status after mutate:
+ *   const result = await mutate(body);
+ *   if (result.status === "success") navigate(`/item/${result.data.id}`);
+ *   if (result.status === "queued") navigate("/items");
+ *   if (result.status === "error") setError(result.error.message);
  */
 export function useMutation<TData = unknown>(
   url: string,
   options: UseMutationOptions<TData> = {},
 ) {
-  const [state, setState] = useState<{
-    data: TData | null;
-    error: Error | null;
-    isLoading: boolean;
-    isError: boolean;
-    isSuccess: boolean;
-  }>({
-    data: null,
-    error: null,
-    isLoading: false,
-    isError: false,
-    isSuccess: false,
-  });
-
+  const [lastResult, setLastResult] = useState<MutateResult<TData> | null>(
+    null,
+  );
+  const [isLoading, setIsLoading] = useState(false);
   const [mutationId, setMutationId] = useState<string | null>(null);
   const optionsRef = useRef(options);
   const urlRef = useRef(url);
@@ -77,61 +79,62 @@ export function useMutation<TData = unknown>(
     async (
       body?: unknown,
       callbacks?: MutateCallbacks<TData>,
-    ): Promise<TData | null> => {
+    ): Promise<MutateResult<TData>> => {
       const key = optionsRef.current.mutationKey;
-      if (key && inFlightKeys.current.has(key)) return null;
+      if (key && inFlightKeys.current.has(key)) return { status: "skipped" };
       if (key) inFlightKeys.current.add(key);
 
-      let retriesLeft = optionsRef.current.retry === true
-        ? Infinity
-        : (optionsRef.current.retry ?? 0);
+      let retriesLeft: number =
+        optionsRef.current.retry === true
+          ? Infinity
+          : typeof optionsRef.current.retry === "number"
+            ? optionsRef.current.retry
+            : 0;
 
       const mid = "mut-" + crypto.randomUUID();
       setMutationId(mid);
       trackMutation(mid, "pending");
-      setState({
-        data: null,
-        error: null,
-        isLoading: true,
-        isError: false,
-        isSuccess: false,
-      });
+      setIsLoading(true);
 
       optionsRef.current.onMutate?.();
 
-      const attempt = async (): Promise<TData | null> => {
+      const attempt = async (): Promise<MutateResult<TData>> => {
         try {
-          const fetchOptions = { ...optionsRef.current, body };
-          const { response, queued } = await fetchWithCache<TData>(urlRef.current, fetchOptions);
+          const {
+            mutationKey,
+            onMutate,
+            onSuccess,
+            onError,
+            onSettled,
+            retry,
+            ...fetchOnlyOptions
+          } = optionsRef.current;
+          const fetchOptions = { ...fetchOnlyOptions, body };
+          const { response, queued } = await fetchWithCache<TData>(
+            urlRef.current,
+            fetchOptions as FetchWithCacheOptions,
+          );
           if (queued) {
             resolveMutation(mid, null);
-            setState({
-              data: null,
-              error: null,
-              isLoading: false,
-              isError: false,
-              isSuccess: false,
-            });
+            setIsLoading(false);
+            const r: MutateResult<TData> = { status: "queued" };
+            setLastResult(r);
             optionsRef.current.onSettled?.();
             callbacks?.onSettled?.();
             if (key) inFlightKeys.current.delete(key);
-            return null;
+            return r;
           }
           const data: TData = await response.json();
           resolveMutation(mid, data);
-          setState({
-            data,
-            error: null,
-            isLoading: false,
-            isError: false,
-            isSuccess: true,
-          });
+          setIsLoading(false);
+          const r: MutateResult<TData> = { status: "success", data };
+          setLastResult(r);
           optionsRef.current.onSuccess?.(data);
           callbacks?.onSuccess?.(data);
           optionsRef.current.onSettled?.();
           callbacks?.onSettled?.();
           if (key) inFlightKeys.current.delete(key);
-          return data;
+          return r;
         } catch (err) {
           if (retriesLeft > 0) {
             retriesLeft--;
@@ -140,19 +143,15 @@ export function useMutation<TData = unknown>(
           }
           const error = err instanceof Error ? err : new Error(String(err));
           rejectMutation(mid, error);
-          setState({
-            data: null,
-            error,
-            isLoading: false,
-            isError: true,
-            isSuccess: false,
-          });
+          setIsLoading(false);
+          const r: MutateResult<TData> = { status: "error", error };
+          setLastResult(r);
           optionsRef.current.onError?.(error);
           callbacks?.onError?.(error);
           optionsRef.current.onSettled?.();
           callbacks?.onSettled?.();
           if (key) inFlightKeys.current.delete(key);
-          return null;
+          return r;
         }
       };
 
@@ -162,18 +161,20 @@ export function useMutation<TData = unknown>(
   );
 
   const reset = useCallback(() => {
-    setState({
-      data: null,
-      error: null,
-      isLoading: false,
-      isError: false,
-      isSuccess: false,
-    });
+    setLastResult(null);
+    setIsLoading(false);
   }, []);
 
   return {
-    ...state,
     mutate,
+    isLoading,
+    isIdle: lastResult === null,
+    isQueued: lastResult?.status === "queued",
+    isSuccess: lastResult?.status === "success",
+    isError: lastResult?.status === "error",
+    data: lastResult?.status === "success" ? (lastResult.data ?? null) : null,
+    error: lastResult?.status === "error" ? (lastResult.error ?? null) : null,
+    lastResult,
     reset,
     mutationId,
   };

package/templates/react/useMutationQueue.jsx

@@ -1,5 +1,9 @@
 import { useState, useEffect, useCallback } from "react";
-import { getPendingCount, getQueueItems, processMutationQueue } from "../offline/queue.js";
+import {
+  getPendingCount,
+  getQueueItems,
+  processMutationQueue,
+} from "../mutation/queue.js";
 
 /**
  * Reactive mutation queue state: pending count, items, last sync info, and processing flag.

package/templates/react/useMutationQueue.tsx

@@ -1,5 +1,9 @@
 import { useState, useEffect, useCallback } from "react";
-import { getPendingCount, getQueueItems, processMutationQueue } from "../offline/queue.ts";
+import {
+  getPendingCount,
+  getQueueItems,
+  processMutationQueue,
+} from "../mutation/queue.ts";
 import type { MutationQueueItem } from "../swoff.d.ts";
 
 export interface MutationQueueState {
@@ -25,7 +29,9 @@ export interface MutationQueueState {
  *
  * @returns {{ pending, items, lastSync, isProcessing, retryAll }}
  */
-export function useMutationQueue(): MutationQueueState & { retryAll: () => Promise<void> } {
+export function useMutationQueue(): MutationQueueState & {
+  retryAll: () => Promise<void>;
+} {
   const [state, setState] = useState<MutationQueueState>({
     pending: 0,
     items: [],

package/templates/react/useMutationState.jsx

@@ -1,13 +1,12 @@
 import { useSyncExternalStore } from "react";
-import { getMutationState, onMutationStateChange } from "../mutation-state.js";
+import { getMutationState, onMutationStateChange } from "../mutation/state.js";
 
 function subscribeToMutations(cb) {
   return onMutationStateChange(() => cb());
 }
 
 export function useMutationState(id) {
-  return useSyncExternalStore(
-    subscribeToMutations,
-    () => (id ? getMutationState(id) ?? null : null),
+  return useSyncExternalStore(subscribeToMutations, () =>
+    id ? (getMutationState(id) ?? null) : null,
   );
 }

package/templates/react/useMutationState.tsx

@@ -1,9 +1,6 @@
 import { useSyncExternalStore } from "react";
-import {
-  getMutationState,
-  onMutationStateChange,
-} from "../mutation-state.ts";
-import type { MutationState } from "../mutation-state.ts";
+import { getMutationState, onMutationStateChange } from "../mutation/state.ts";
+import type { MutationState } from "../mutation/state.ts";
 
 function subscribeToMutations(cb: () => void) {
   return onMutationStateChange(() => cb());
@@ -18,8 +15,7 @@ function subscribeToMutations(cb: () => void) {
  *   if (mutation?.status === "error") { ... }
  */
 export function useMutationState(id: string | null): MutationState | null {
-  return useSyncExternalStore(
-    subscribeToMutations,
-    () => (id ? getMutationState(id) ?? null : null),
+  return useSyncExternalStore(subscribeToMutations, () =>
+    id ? (getMutationState(id) ?? null) : null,
   );
 }

package/templates/react/useNetworkStatus.jsx

@@ -1,4 +1,9 @@
 import { useState, useEffect, useRef } from "react";
+import {
+  CONNECTIVITY_EVENT,
+  forceRetry,
+  getCurrentOnlineStatus,
+} from "./connectivity.js";
 
 /**
  * Reactive network information: online status, connection type, and bandwidth.
@@ -14,48 +19,83 @@ import { useState, useEffect, useRef } from "react";
  */
 export function useNetworkStatus() {
   const wasOfflineRef = useRef(false);
+  const [isRetrying, setIsRetrying] = useState(false);
 
   const [state, setState] = useState(() => {
-    const online = typeof navigator !== "undefined" ? navigator.onLine : true;
-    const connection = navigator?.connection;
     return {
-      online,
+      online: true,
       wasOffline: false,
       lastChangedAt: null,
-      effectiveType: connection?.effectiveType ?? null,
-      downlink: connection?.downlink ?? null,
+      effectiveType:
+        (typeof navigator !== "undefined" &&
+          navigator.connection?.effectiveType) ||
+        null,
+      downlink:
+        (typeof navigator !== "undefined" && navigator.connection?.downlink) ||
+        null,
     };
   });
 
+  // Manual trigger wrapper that handles local loading state
+  const retry = async () => {
+    setIsRetrying(true);
+    await forceRetry();
+    setIsRetrying(false);
+  };
+
   useEffect(() => {
-    const onOnline = () => {
-      setState((s) => ({ ...s, online: true, lastChangedAt: Date.now() }));
-    };
-    const onOffline = () => {
+    // Sync with actual status after mount — prevents SSR hydration mismatch
+    // where the server defaults to online:true but the browser is offline.
+    if (!getCurrentOnlineStatus()) {
       wasOfflineRef.current = true;
-      setState((s) => ({ ...s, online: false, lastChangedAt: Date.now(), wasOffline: true }));
+      setState((s) => ({
+        ...s,
+        online: false,
+        wasOffline: true,
+        lastChangedAt: Date.now(),
+      }));
+    }
+
+    const connection = navigator.connection;
+
+    const handleConnectivityChange = (e) => {
+      const isTrulyOnline = e.detail.online;
+
+      if (!isTrulyOnline) {
+        wasOfflineRef.current = true;
+      } else {
+        wasOfflineRef.current = false;
+      }
+
+      setState((s) => ({
+        ...s,
+        online: isTrulyOnline,
+        wasOffline: wasOfflineRef.current,
+        lastChangedAt: Date.now(),
+      }));
     };
 
-    const connection = navigator?.connection;
     const onTypeChange = () => {
       if (!connection) return;
-      setState((s) => ({ ...s, effectiveType: connection.effectiveType, downlink: connection.downlink }));
+      setState((s) => ({
+        ...s,
+        effectiveType: connection.effectiveType,
+        downlink: connection.downlink,
+      }));
     };
 
-    window.addEventListener("online", onOnline);
-    window.addEventListener("offline", onOffline);
+    window.addEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
     if (connection) {
       connection.addEventListener("change", onTypeChange);
     }
 
     return () => {
-      window.removeEventListener("online", onOnline);
-      window.removeEventListener("offline", onOffline);
+      window.removeEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
       if (connection) {
         connection.removeEventListener("change", onTypeChange);
       }
     };
   }, []);
 
-  return state;
+  return { ...state, isRetrying, retry };
 }

package/templates/react/useNetworkStatus.tsx

@@ -1,4 +1,9 @@
 import { useState, useEffect, useRef } from "react";
+import {
+  CONNECTIVITY_EVENT,
+  forceRetry,
+  getCurrentOnlineStatus,
+} from "../connectivity.ts";
 
 /**
  * Reactive network information: online status, connection type, and bandwidth.
@@ -12,65 +17,82 @@ import { useState, useEffect, useRef } from "react";
  *   // Warn on slow connection:
  *   if (online && effectiveType === "2g") return <SlowConnectionWarning />;
  *
- * @returns {{ online: boolean, wasOffline: boolean, lastChangedAt: number | null, effectiveType: string | null, downlink: number | null }}
+ * @returns {{ online: boolean, wasOffline: boolean, lastChangedAt: number | null, effectiveType: string | null, downlink: number | null, isRetrying: boolean, retry: () => Promise<void> }}
  */
 export function useNetworkStatus() {
   const wasOfflineRef = useRef(false);
+  const [isRetrying, setIsRetrying] = useState(false);
 
   const [state, setState] = useState(() => {
-    const online = typeof navigator !== "undefined" ? navigator.onLine : true;
-    const connection = navigator?.connection;
     return {
-      online,
+      online: true,
       wasOffline: false,
       lastChangedAt: null as number | null,
-      effectiveType: connection?.effectiveType ?? null,
-      downlink: connection?.downlink ?? null,
+      effectiveType: null as string | null,
+      downlink: null as number | null,
     };
   });
 
+  // Manual trigger wrapper that handles local loading state
+  const retry = async () => {
+    setIsRetrying(true);
+    await forceRetry();
+    setIsRetrying(false);
+  };
+
   useEffect(() => {
-    const onOnline = () => {
+    // Sync with actual status after mount — prevents SSR hydration mismatch
+    // where the server defaults to online:true but the browser is offline.
+    if (!getCurrentOnlineStatus()) {
+      wasOfflineRef.current = true;
       setState((s) => ({
         ...s,
-        online: true,
+        online: false,
+        wasOffline: true,
         lastChangedAt: Date.now(),
       }));
-    };
-    const onOffline = () => {
-      wasOfflineRef.current = true;
+    }
+
+    const connection = navigator.connection;
+
+    const handleConnectivityChange = (e: Event) => {
+      const isTrulyOnline = (e as CustomEvent).detail.online;
+
+      if (!isTrulyOnline) {
+        wasOfflineRef.current = true;
+      } else {
+        wasOfflineRef.current = false;
+      }
+
       setState((s) => ({
         ...s,
-        online: false,
+        online: isTrulyOnline,
+        wasOffline: wasOfflineRef.current,
         lastChangedAt: Date.now(),
-        wasOffline: true,
       }));
     };
 
-    const connection = navigator?.connection;
     const onTypeChange = () => {
       if (!connection) return;
-      setState((s) => ({
+      setState((s: typeof state) => ({
         ...s,
         effectiveType: connection.effectiveType,
         downlink: connection.downlink,
       }));
     };
 
-    window.addEventListener("online", onOnline);
-    window.addEventListener("offline", onOffline);
+    window.addEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
     if (connection) {
       connection.addEventListener("change", onTypeChange);
     }
 
     return () => {
-      window.removeEventListener("online", onOnline);
-      window.removeEventListener("offline", onOffline);
+      window.removeEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
       if (connection) {
         connection.removeEventListener("change", onTypeChange);
       }
     };
   }, []);
 
-  return state;
+  return { ...state, isRetrying, retry };
 }

package/templates/react/useOfflineAnalytics.jsx

@@ -0,0 +1,42 @@
+import { useState, useEffect, useCallback } from "react";
+
+/**
+ * Tracks offline navigation fallback events dispatched by the Service Worker.
+ *
+ * Usage:
+ *   const { lastEvent, events } = useOfflineAnalytics();
+ *
+ *   // Render an offline indicator when a fallback was served:
+ *   if (lastEvent) {
+ *     return <div>Offline: served {lastEvent.fallbackLevel} for {lastEvent.route}</div>;
+ *   }
+ *
+ *   // Or pass a callback:
+ *   useOfflineAnalytics((event) => console.log("Fallback:", event));
+ */
+export function useOfflineAnalytics(callback) {
+  const [events, setEvents] = useState([]);
+  const [lastEvent, setLastEvent] = useState(null);
+
+  const handler = useCallback((event) => {
+    if (event.data?.type === "OFFLINE_FALLBACK_ACTIVATED" && event.data?.detail) {
+      const detail = event.data.detail;
+      setEvents((prev) => [...prev, detail]);
+      setLastEvent(detail);
+      callback?.(detail);
+    }
+  }, [callback]);
+
+  useEffect(() => {
+    if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
+    navigator.serviceWorker.addEventListener("message", handler);
+    return () => navigator.serviceWorker.removeEventListener("message", handler);
+  }, [handler]);
+
+  const clear = useCallback(() => {
+    setEvents([]);
+    setLastEvent(null);
+  }, []);
+
+  return { lastEvent, events, clear };
+}

package/templates/react/useOfflineAnalytics.tsx

@@ -0,0 +1,50 @@
+import { useState, useEffect, useCallback } from "react";
+
+export interface OfflineFallbackEvent {
+  route: string;
+  fallbackLevel: "route-fallback" | "offline-page" | "spa-shell" | "inline-503";
+  timestamp: number;
+}
+
+/**
+ * Tracks offline navigation fallback events dispatched by the Service Worker.
+ *
+ * Usage:
+ *   const { lastEvent, events } = useOfflineAnalytics();
+ *
+ *   // Render an offline indicator when a fallback was served:
+ *   if (lastEvent) {
+ *     return <div>Offline: served {lastEvent.fallbackLevel} for {lastEvent.route}</div>;
+ *   }
+ *
+ *   // Or pass a callback:
+ *   useOfflineAnalytics((event) => console.log("Fallback:", event));
+ *
+ * @returns {{ lastEvent: OfflineFallbackEvent | null, events: OfflineFallbackEvent[], clear: () => void }}
+ */
+export function useOfflineAnalytics(callback?: (event: OfflineFallbackEvent) => void) {
+  const [events, setEvents] = useState<OfflineFallbackEvent[]>([]);
+  const [lastEvent, setLastEvent] = useState<OfflineFallbackEvent | null>(null);
+
+  const handler = useCallback((event: MessageEvent) => {
+    if (event.data?.type === "OFFLINE_FALLBACK_ACTIVATED" && event.data?.detail) {
+      const detail = event.data.detail as OfflineFallbackEvent;
+      setEvents((prev) => [...prev, detail]);
+      setLastEvent(detail);
+      callback?.(detail);
+    }
+  }, [callback]);
+
+  useEffect(() => {
+    if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
+    navigator.serviceWorker.addEventListener("message", handler);
+    return () => navigator.serviceWorker.removeEventListener("message", handler);
+  }, [handler]);
+
+  const clear = useCallback(() => {
+    setEvents([]);
+    setLastEvent(null);
+  }, []);
+
+  return { lastEvent, events, clear };
+}

package/templates/react/usePwaInstall.jsx

@@ -0,0 +1,26 @@
+import { useState, useEffect, useCallback } from "react";
+import { isInstallable, promptInstall } from "../pwa/prompt.js";
+
+export function usePwaInstall() {
+  const [canInstall, setCanInstall] = useState(false);
+
+  useEffect(() => {
+    const onReady = () => setCanInstall(true);
+    const onDone = () => setCanInstall(false);
+
+    window.addEventListener("pwa-installable", onReady);
+    window.addEventListener("pwa-installed", onDone);
+    window.addEventListener("pwa-dismissed", onDone);
+    return () => {
+      window.removeEventListener("pwa-installable", onReady);
+      window.removeEventListener("pwa-installed", onDone);
+      window.removeEventListener("pwa-dismissed", onDone);
+    };
+  }, []);
+
+  const install = useCallback(async () => {
+    await promptInstall();
+  }, []);
+
+  return { canInstall, install };
+}

package/templates/react/usePwaInstall.tsx

@@ -0,0 +1,26 @@
+import { useState, useEffect, useCallback } from "react";
+import { isInstallable, promptInstall } from "../pwa/prompt.ts";
+
+export function usePwaInstall() {
+  const [canInstall, setCanInstall] = useState(false);
+
+  useEffect(() => {
+    const onReady = () => setCanInstall(true);
+    const onDone = () => setCanInstall(false);
+
+    window.addEventListener("pwa-installable", onReady);
+    window.addEventListener("pwa-installed", onDone);
+    window.addEventListener("pwa-dismissed", onDone);
+    return () => {
+      window.removeEventListener("pwa-installable", onReady);
+      window.removeEventListener("pwa-installed", onDone);
+      window.removeEventListener("pwa-dismissed", onDone);
+    };
+  }, []);
+
+  const install = useCallback(async () => {
+    await promptInstall();
+  }, []);
+
+  return { canInstall, install };
+}