@ovineko/spa-guard-react 0.0.1-alpha-18

package/dist/DefaultErrorFallback.d.ts

@@ -0,0 +1,17 @@
+import type { SpaGuardState } from "@ovineko/spa-guard/runtime";
+interface DefaultErrorFallbackProps {
+    error: unknown;
+    isChunkError: boolean;
+    isRetrying: boolean;
+    onReset?: () => void;
+    spaGuardState: SpaGuardState;
+}
+/**
+ * Default fallback UI component for error boundaries.
+ *
+ * Uses two separate HTML templates: one for loading/retrying state
+ * and one for error state. Renders via dangerouslySetInnerHTML with
+ * virtual container + data attribute patching for dynamic content.
+ */
+export declare const DefaultErrorFallback: React.FC<DefaultErrorFallbackProps>;
+export {};

package/dist/chunk-RR7KT33N.js

@@ -0,0 +1,223 @@
+// src/react/index.tsx
+import { useEffect as useEffect3, useState as useState3 } from "react";
+import { getState, subscribeToState } from "@ovineko/spa-guard/runtime";
+
+// src/DefaultErrorFallback.tsx
+import { useLayoutEffect, useMemo, useRef } from "react";
+import {
+  applyI18n,
+  defaultErrorFallbackHtml,
+  defaultLoadingFallbackHtml,
+  getI18n,
+  getOptions
+} from "@ovineko/spa-guard/_internal";
+import { jsx } from "react/jsx-runtime";
+var escapeHtml = (str) => str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+var reloadHandler = () => location.reload();
+function buildHtml(template, patches) {
+  const container = document.createElement("div");
+  container.innerHTML = template;
+  if (patches.spinnerHtml) {
+    const spinnerEl = container.querySelector("[data-spa-guard-spinner]");
+    if (spinnerEl) {
+      spinnerEl.innerHTML = patches.spinnerHtml;
+    }
+  }
+  if (patches.content) {
+    for (const [key, value] of Object.entries(patches.content)) {
+      const el = container.querySelector(`[data-spa-guard-content="${key}"]`);
+      if (el) {
+        el.innerHTML = value;
+      }
+    }
+  }
+  if (patches.sections) {
+    for (const [key, visible] of Object.entries(patches.sections)) {
+      const el = container.querySelector(`[data-spa-guard-section="${key}"]`);
+      if (el) {
+        el.style.display = visible ? "block" : "none";
+      }
+    }
+  }
+  if (patches.actions) {
+    for (const [key, visible] of Object.entries(patches.actions)) {
+      const el = container.querySelector(`[data-spa-guard-action="${key}"]`);
+      if (el) {
+        el.style.display = visible ? "inline-block" : "none";
+      }
+    }
+  }
+  const t = getI18n();
+  if (t) {
+    applyI18n(container, t);
+  }
+  return container.innerHTML;
+}
+var DefaultErrorFallback = ({
+  error,
+  isChunkError: isChunk,
+  isRetrying,
+  onReset,
+  spaGuardState
+}) => {
+  const containerRef = useRef(null);
+  const html = useMemo(() => {
+    const opts = getOptions();
+    if (isRetrying) {
+      const loadingTemplate = opts.html?.loading?.content ?? defaultLoadingFallbackHtml;
+      return buildHtml(loadingTemplate, {
+        content: {
+          attempt: String(spaGuardState.currentAttempt)
+        },
+        sections: {
+          retrying: true
+        },
+        spinnerHtml: opts.spinner?.content
+      });
+    }
+    const heading = isChunk ? "Failed to load module" : "Something went wrong";
+    const message = error instanceof Error ? error.message : String(error);
+    const errorTemplate = opts.html?.fallback?.content ?? defaultErrorFallbackHtml;
+    return buildHtml(errorTemplate, {
+      actions: {
+        "try-again": Boolean(onReset)
+      },
+      content: {
+        heading: escapeHtml(heading),
+        message: escapeHtml(message)
+      }
+    });
+  }, [isRetrying, isChunk, error, onReset, spaGuardState.currentAttempt]);
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) {
+      return;
+    }
+    const reloadBtn = el.querySelector('[data-spa-guard-action="reload"]');
+    reloadBtn?.addEventListener("click", reloadHandler);
+    const tryAgainHandler = onReset ? () => onReset() : null;
+    const tryAgainBtn = onReset ? el.querySelector('[data-spa-guard-action="try-again"]') : null;
+    if (tryAgainHandler && tryAgainBtn) {
+      tryAgainBtn.addEventListener("click", tryAgainHandler);
+    }
+    return () => {
+      reloadBtn?.removeEventListener("click", reloadHandler);
+      if (tryAgainHandler && tryAgainBtn) {
+        tryAgainBtn.removeEventListener("click", tryAgainHandler);
+      }
+    };
+  }, [onReset, html]);
+  const innerHtml = useMemo(() => ({ __html: html }), [html]);
+  return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: innerHtml, ref: containerRef });
+};
+
+// src/react/DebugSyncErrorTrigger.tsx
+import { useEffect, useState } from "react";
+import { debugSyncErrorEventType } from "@ovineko/spa-guard/_internal";
+function DebugSyncErrorTrigger() {
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    const handler = (e) => {
+      const detail = e.detail;
+      if (detail?.error instanceof Error) {
+        setError(detail.error);
+      }
+    };
+    globalThis.addEventListener(debugSyncErrorEventType, handler);
+    return () => {
+      globalThis.removeEventListener(debugSyncErrorEventType, handler);
+    };
+  }, []);
+  if (error) {
+    throw error;
+  }
+  return null;
+}
+
+// src/react/lazyWithRetry.tsx
+import { lazy } from "react";
+import { getOptions as getOptions2, retryImport } from "@ovineko/spa-guard/_internal";
+var lazyWithRetry = (importFn, options) => {
+  return lazy(() => {
+    const globalLazyRetry = getOptions2().lazyRetry ?? {};
+    const retryDelays = options?.retryDelays ?? globalLazyRetry.retryDelays ?? [1e3, 2e3];
+    const callReloadOnFailure = options?.callReloadOnFailure ?? globalLazyRetry.callReloadOnFailure ?? true;
+    const signal = options?.signal;
+    return retryImport(importFn, retryDelays, { callReloadOnFailure, signal });
+  });
+};
+
+// src/react/Spinner.tsx
+import { useMemo as useMemo2 } from "react";
+import { getOptions as getOptions3 } from "@ovineko/spa-guard/_internal";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function Spinner(props) {
+  const opts = getOptions3();
+  const content = opts.spinner?.disabled ? void 0 : opts.spinner?.content;
+  const innerHtml = useMemo2(() => content ? { __html: content } : null, [content]);
+  if (!innerHtml) {
+    return null;
+  }
+  return /* @__PURE__ */ jsx2("div", { ...props, dangerouslySetInnerHTML: innerHtml });
+}
+
+// src/react/useSPAGuardChunkError.ts
+import { useCallback, useState as useState2 } from "react";
+
+// src/react/useSPAGuardEvents.ts
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+import { subscribe } from "@ovineko/spa-guard/_internal";
+var useSPAGuardEvents = (callback) => {
+  const callbackRef = useRef2(callback);
+  useEffect2(() => {
+    callbackRef.current = callback;
+  });
+  useEffect2(() => {
+    return subscribe((event) => {
+      callbackRef.current(event);
+    });
+  }, []);
+};
+
+// src/react/useSPAGuardChunkError.ts
+var useSPAGuardChunkError = () => {
+  const [chunkError, setChunkError] = useState2(null);
+  useSPAGuardEvents(
+    useCallback((event) => {
+      if (event.name === "chunk-error") {
+        setChunkError(event);
+      }
+    }, [])
+  );
+  return chunkError;
+};
+
+// src/react/index.tsx
+import { ForceRetryError } from "@ovineko/spa-guard";
+var useSpaGuardState = () => {
+  const [state, setState] = useState3(() => {
+    if (globalThis.window === void 0) {
+      return {
+        currentAttempt: 0,
+        isFallbackShown: false,
+        isWaiting: false
+      };
+    }
+    return getState();
+  });
+  useEffect3(() => {
+    return subscribeToState(setState);
+  }, []);
+  return state;
+};
+
+export {
+  DefaultErrorFallback,
+  DebugSyncErrorTrigger,
+  lazyWithRetry,
+  Spinner,
+  useSPAGuardEvents,
+  useSPAGuardChunkError,
+  useSpaGuardState,
+  ForceRetryError
+};

package/dist/react/DebugSyncErrorTrigger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Renders nothing normally. When a CustomEvent of type debugSyncErrorEventType
+ * is dispatched on window, this component stores the error in state and throws
+ * it during the next render, allowing a parent React Error Boundary to catch it.
+ *
+ * Place this component inside your ErrorBoundary:
+ *
+ *   <ErrorBoundary fallback={<CrashPage />}>
+ *     <DebugSyncErrorTrigger />
+ *     <App />
+ *   </ErrorBoundary>
+ */
+export declare function DebugSyncErrorTrigger(): null;

package/dist/react/Spinner.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentProps } from "react";
+type SpinnerProps = Omit<ComponentProps<"div">, "children" | "dangerouslySetInnerHTML">;
+/**
+ * Renders the spa-guard spinner inside a div.
+ * Returns null if spinner is disabled or no content available.
+ * All div props forwarded to wrapper element.
+ */
+export declare function Spinner(props: SpinnerProps): null | React.ReactElement;
+export {};

package/dist/react/index.d.ts

@@ -0,0 +1,10 @@
+export { DefaultErrorFallback } from "../DefaultErrorFallback";
+export { DebugSyncErrorTrigger } from "./DebugSyncErrorTrigger";
+export { lazyWithRetry } from "./lazyWithRetry";
+export { Spinner } from "./Spinner";
+export type { LazyRetryOptions } from "./types";
+export { useSPAGuardChunkError } from "./useSPAGuardChunkError";
+export { useSPAGuardEvents } from "./useSPAGuardEvents";
+export { ForceRetryError } from "@ovineko/spa-guard";
+export type { SpaGuardState } from "@ovineko/spa-guard/runtime";
+export declare const useSpaGuardState: () => import("@ovineko/spa-guard/runtime").SpaGuardState;

package/dist/react/index.js

@@ -0,0 +1,20 @@
+import {
+  DebugSyncErrorTrigger,
+  DefaultErrorFallback,
+  ForceRetryError,
+  Spinner,
+  lazyWithRetry,
+  useSPAGuardChunkError,
+  useSPAGuardEvents,
+  useSpaGuardState
+} from "../chunk-RR7KT33N.js";
+export {
+  DebugSyncErrorTrigger,
+  DefaultErrorFallback,
+  ForceRetryError,
+  Spinner,
+  lazyWithRetry,
+  useSPAGuardChunkError,
+  useSPAGuardEvents,
+  useSpaGuardState
+};

package/dist/react/lazyWithRetry.d.ts

@@ -0,0 +1,34 @@
+import { type ComponentType, type LazyExoticComponent } from "react";
+import type { LazyRetryOptions } from "./types";
+export type { LazyRetryOptions } from "./types";
+/**
+ * Creates a lazy-loaded React component with automatic retry on chunk load failures.
+ *
+ * On import failure, retries with configurable delays before falling back to
+ * `attemptReload()` for a full page reload.
+ *
+ * @param importFn - Function that performs the dynamic import
+ * @param options - Per-import options that override global lazyRetry options
+ * @returns A lazy React component with retry logic
+ *
+ * @example
+ * // Basic usage with global options
+ * const LazyHome = lazyWithRetry(() => import('./pages/Home'));
+ *
+ * @example
+ * // Override retry delays for a critical component
+ * const LazyCheckout = lazyWithRetry(
+ *   () => import('./pages/Checkout'),
+ *   { retryDelays: [500, 1000, 2000, 4000] }
+ * );
+ *
+ * @example
+ * // Disable page reload for a non-critical component
+ * const LazyWidget = lazyWithRetry(
+ *   () => import('./widgets/Optional'),
+ *   { retryDelays: [1000], callReloadOnFailure: false }
+ * );
+ */
+export declare const lazyWithRetry: <T extends ComponentType<any>>(importFn: () => Promise<{
+    default: T;
+}>, options?: LazyRetryOptions) => LazyExoticComponent<T>;

package/dist/react/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-import options for lazyWithRetry that override global lazyRetry options.
+ *
+ * @example
+ * // Override retry delays for a critical component
+ * const LazyCheckout = lazyWithRetry(
+ *   () => import('./pages/Checkout'),
+ *   { retryDelays: [500, 1000, 2000, 4000] } satisfies LazyRetryOptions
+ * );
+ */
+export interface LazyRetryOptions {
+    /**
+     * Call attemptReload() after all retry attempts are exhausted.
+     * If true, triggers page reload logic after all retries fail.
+     * If false, only throws the error to the error boundary without reload.
+     * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.callReloadOnFailure`.
+     *
+     * @default true (inherited from global options)
+     */
+    callReloadOnFailure?: boolean;
+    /**
+     * Array of delays in milliseconds for retry attempts.
+     * Each element represents one retry attempt with the given delay.
+     * The number of elements determines the number of retry attempts.
+     * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.retryDelays`.
+     *
+     * @default [1000, 2000] (inherited from global options)
+     * @example [500, 1500, 3000] // 3 attempts: 500ms, 1.5s, 3s
+     */
+    retryDelays?: number[];
+    /**
+     * AbortSignal to cancel pending retry delays between import attempts.
+     * When the signal fires, any pending setTimeout between retries is cleared
+     * and the import promise rejects with an AbortError.
+     *
+     * Note: cancels only the wait periods between retry attempts, not an in-flight
+     * dynamic import (JavaScript does not support cancelling in-flight module fetches).
+     * Most useful when calling `retryImport` directly rather than through `lazyWithRetry`,
+     * since `lazyWithRetry` captures the signal at module scope (not per component instance).
+     */
+    signal?: AbortSignal;
+}

package/dist/react/useSPAGuardChunkError.d.ts

@@ -0,0 +1,2 @@
+import type { SPAGuardEventChunkError } from "@ovineko/spa-guard/_internal";
+export declare const useSPAGuardChunkError: () => null | SPAGuardEventChunkError;

package/dist/react/useSPAGuardEvents.d.ts

@@ -0,0 +1,2 @@
+import type { SPAGuardEvent } from "@ovineko/spa-guard/_internal";
+export declare const useSPAGuardEvents: (callback: (event: SPAGuardEvent) => void) => void;

package/dist/react-error-boundary/index.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import { type SpaGuardState } from "../react";
+/**
+ * Props for the ErrorBoundary component
+ */
+export interface ErrorBoundaryProps {
+    autoRetryChunkErrors?: boolean;
+    children: ReactNode;
+    fallback?: ((props: FallbackProps) => React.ReactElement) | React.ComponentType<FallbackProps>;
+    fallbackRender?: (props: FallbackProps) => React.ReactElement;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    resetKeys?: Array<unknown>;
+    sendBeaconOnError?: boolean;
+}
+/**
+ * Props passed to the fallback component when an error is caught
+ */
+export interface FallbackProps {
+    error: Error;
+    errorInfo: null | React.ErrorInfo;
+    isChunkError: boolean;
+    isRetrying: boolean;
+    resetError: () => void;
+    spaGuardState: SpaGuardState;
+}
+/**
+ * Error boundary component with spa-guard integration.
+ *
+ * Catches errors in child components and automatically retries chunk loading errors.
+ */
+export declare const ErrorBoundary: React.FC<ErrorBoundaryProps>;

package/dist/react-error-boundary/index.js

@@ -0,0 +1,83 @@
+import {
+  DefaultErrorFallback,
+  useSpaGuardState
+} from "../chunk-RR7KT33N.js";
+
+// src/react-error-boundary/index.tsx
+import { Component } from "react";
+import { handleErrorWithSpaGuard, isChunkError } from "@ovineko/spa-guard/_internal";
+import { jsx } from "react/jsx-runtime";
+var DefaultFallback = ({
+  error,
+  isChunkError: isChunk,
+  isRetrying,
+  resetError,
+  spaGuardState
+}) => /* @__PURE__ */ jsx(
+  DefaultErrorFallback,
+  {
+    error,
+    isChunkError: isChunk,
+    isRetrying,
+    onReset: resetError,
+    spaGuardState
+  }
+);
+var ErrorBoundaryImpl = class extends Component {
+  state = { error: null, errorInfo: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, errorInfo) {
+    this.setState({ errorInfo });
+    const { autoRetryChunkErrors, onError, sendBeaconOnError } = this.props;
+    handleErrorWithSpaGuard(error, {
+      autoRetryChunkErrors,
+      errorInfo,
+      eventName: "react-error-boundary",
+      onError: () => onError?.(error, errorInfo),
+      sendBeaconOnError
+    });
+  }
+  componentDidUpdate(prevProps) {
+    const { resetKeys = [] } = this.props;
+    const prevResetKeys = prevProps.resetKeys ?? [];
+    if (resetKeys.length !== prevResetKeys.length || resetKeys.some((key, i) => key !== prevResetKeys[i])) {
+      this.resetError();
+    }
+  }
+  render() {
+    const { error, errorInfo } = this.state;
+    if (!error) {
+      return this.props.children;
+    }
+    const { fallback: Fallback, fallbackRender, spaGuardState } = this.props;
+    const isChunk = isChunkError(error);
+    const isRetrying = spaGuardState.isWaiting && spaGuardState.currentAttempt > 0;
+    const fallbackProps = {
+      error,
+      errorInfo,
+      isChunkError: isChunk,
+      isRetrying,
+      resetError: this.resetError,
+      spaGuardState
+    };
+    if (fallbackRender) {
+      return fallbackRender(fallbackProps);
+    }
+    if (Fallback) {
+      return /* @__PURE__ */ jsx(Fallback, { ...fallbackProps });
+    }
+    return /* @__PURE__ */ jsx(DefaultFallback, { ...fallbackProps });
+  }
+  resetError = () => {
+    this.setState({ error: null, errorInfo: null });
+  };
+};
+var ErrorBoundary = (props) => {
+  const spaGuardState = useSpaGuardState();
+  return /* @__PURE__ */ jsx(ErrorBoundaryImpl, { ...props, spaGuardState });
+};
+export {
+  ErrorBoundary
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ovineko/spa-guard-react",
+  "version": "0.0.1-alpha-18",
+  "description": "React hooks, components, and error boundaries for spa-guard",
+  "keywords": [
+    "spa",
+    "react",
+    "error-boundary",
+    "chunk-load-error"
+  ],
+  "homepage": "https://github.com/ovineko/ovineko/tree/main/spa-guard/react",
+  "bugs": {
+    "url": "https://github.com/ovineko/ovineko/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ovineko/ovineko.git",
+    "directory": "spa-guard/react"
+  },
+  "license": "MIT",
+  "author": "Alexander Svinarev <shibanet0@gmail.com> (shibanet0.com)",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./error-boundary": {
+      "types": "./dist/react-error-boundary/index.d.ts",
+      "default": "./dist/react-error-boundary/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ovineko/spa-guard": "0.0.1-alpha-18"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}