feat(react): add Suspense fallback to LingoProviderWrapper

.changeset/suspense-fallback.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_react": minor
+---
+
+add Suspense fallback to LingoProviderWrapper
+

demo/vite-project/src/main.tsx

@@ -4,11 +4,18 @@ import "./index.css";
 import App from "./App.tsx";
 
 // Compiler: add import
-import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
+import {
+  LingoProviderFallback,
+  LingoProviderWrapper,
+  loadDictionary,
+} from "lingo.dev/react/client";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
+    <LingoProviderWrapper
+      loadDictionary={(locale) => loadDictionary(locale)}
+      fallback={<LingoProviderFallback />}
+    >
       <App />
     </LingoProviderWrapper>
   </StrictMode>,

packages/react/src/client/provider.spec.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { act, render, screen, waitFor } from "@testing-library/react";
 import React from "react";
 import { LingoProvider, LingoProviderWrapper } from "./provider";
 import { LingoContext } from "./context";
@@ -52,10 +52,9 @@ describe("client/provider", () => {
   });
 
   describe("LingoProviderWrapper", () => {
-    it("loads dictionary and renders children; returns null while loading", async () => {
-      const loadDictionary = vi
-        .fn()
-        .mockResolvedValue({ locale: "en", files: {} });
+    it("renders nothing while loading by default, then shows children", async () => {
+      const deferred = createDeferred<{ locale: string; files: Record<string, unknown> }>();
+      const loadDictionary = vi.fn(() => deferred.promise);
 
       const Child = () => <div data-testid="child">ok</div>;
 
@@ -65,24 +64,91 @@ describe("client/provider", () => {
         </LingoProviderWrapper>,
       );
 
-      // initially null during loading
+      // No fallback by default (renders nothing during load)
       expect(container.firstChild).toBeNull();
 
+      await act(async () => {
+        deferred.resolve({ locale: "en", files: {} });
+        await deferred.promise;
+      });
+
       await waitFor(() => expect(loadDictionary).toHaveBeenCalled());
       const child = await findByTestId("child");
-      expect(child != null).toBe(true);
+      expect(child).not.toBeNull();
     });
 
-    it("swallows load errors and stays null", async () => {
-      const loadDictionary = vi.fn().mockRejectedValue(new Error("boom"));
-      const { container } = render(
-        <LingoProviderWrapper loadDictionary={loadDictionary}>
+    it("supports a custom fallback", () => {
+      const loadDictionary = vi.fn(() => new Promise(() => {}));
+
+      render(
+        <LingoProviderWrapper
+          loadDictionary={loadDictionary}
+          fallback={<div data-testid="fallback">waiting</div>}
+        >
           <div />
         </LingoProviderWrapper>,
       );
 
-      await vi.waitFor(() => expect(loadDictionary).toHaveBeenCalled());
-      expect(container.firstChild).toBeNull();
+      const fallback = screen.getByTestId("fallback");
+      expect(fallback).not.toBeNull();
+      expect(fallback.textContent).toBe("waiting");
+    });
+
+    it("propagates load errors to the nearest error boundary", async () => {
+      const loadDictionary = vi.fn().mockRejectedValue(new Error("boom"));
+      const onError = vi.fn();
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      render(
+        <TestErrorBoundary onError={onError}>
+          <LingoProviderWrapper loadDictionary={loadDictionary}>
+            <div />
+          </LingoProviderWrapper>
+        </TestErrorBoundary>,
+      );
+
+      await waitFor(() => expect(onError).toHaveBeenCalled());
+      expect(onError.mock.calls[0][0]).toBeInstanceOf(Error);
+      expect(onError.mock.calls[0][0].message).toBe("boom");
+
+      const errorBoundary = await screen.findByTestId("boundary-error");
+      expect(errorBoundary).not.toBeNull();
+      expect(errorBoundary.textContent).toBe("error");
+
+      consoleSpy.mockRestore();
     });
   });
 });
+
+function createDeferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+class TestErrorBoundary extends React.Component<
+  { onError: (error: Error) => void; children: React.ReactNode },
+  { hasError: boolean }
+> {
+  state = { hasError: false };
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error) {
+    this.props.onError(error);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div data-testid="boundary-error">error</div>;
+    }
+
+    return this.props.children;
+  }
+}

packages/react/src/client/provider.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { Suspense, useMemo } from "react";
+import type { ReactNode } from "react";
 import { LingoContext } from "./context";
 import { getLocaleFromCookies } from "./utils";
 
@@ -15,7 +16,7 @@ export type LingoProviderProps<D> = {
   /**
    * The child components containing localizable content.
    */
-  children: React.ReactNode;
+  children: ReactNode;
 };
 
 /**
@@ -78,7 +79,6 @@ export type LingoProviderProps<D> = {
  * ```
  */
 export function LingoProvider<D>(props: LingoProviderProps<D>) {
-  // TODO: handle case when no dictionary is provided - throw suspense? return null / other fallback?
   if (!props.dictionary) {
     throw new Error("LingoProvider: dictionary is not provided.");
   }
@@ -106,7 +106,11 @@ export type LingoProviderWrapperProps<D> = {
   /**
    * The child components containing localizable content.
    */
-  children: React.ReactNode;
+  children: ReactNode;
+  /**
+   * Optional fallback element rendered while the dictionary is loading.
+   */
+  fallback?: ReactNode;
 };
 
 /**
@@ -116,51 +120,111 @@ export type LingoProviderWrapperProps<D> = {
  *
  * - Should be placed at the top of the component tree
  * - Should be used in purely client-side rendered applications (e.g., Vite-based apps)
+ * - Suspends rendering while the dictionary loads (no UI by default, opt-in with `fallback` prop)
  *
  * @template D - The type of the dictionary object containing localized content.
  *
- * @example Use in a Vite application
+ * @example Use in a Vite application with loading UI
  * ```tsx file="src/main.tsx"
- * import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
+ * import { LingoProviderFallback, LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
  * import { StrictMode } from 'react'
  * import { createRoot } from 'react-dom/client'
  * import './index.css'
  * import App from './App.tsx'
  *
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
- *     <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
+ *     <LingoProviderWrapper
+ *       loadDictionary={(locale) => loadDictionary(locale)}
+ *       fallback={<LingoProviderFallback />}
+ *     >
  *       <App />
  *     </LingoProviderWrapper>
  *   </StrictMode>,
  * );
  * ```
  */
 export function LingoProviderWrapper<D>(props: LingoProviderWrapperProps<D>) {
-  const [dictionary, setDictionary] = useState<D | null>(null);
-
-  // for client-side rendered apps, the dictionary is also loaded on the client
-  useEffect(() => {
-    (async () => {
-      try {
-        const locale = getLocaleFromCookies();
-        console.log(
-          `[Lingo.dev] Loading dictionary file for locale ${locale}...`,
-        );
-        const localeDictionary = await props.loadDictionary(locale);
-        setDictionary(localeDictionary);
-      } catch (error) {
-        console.log("[Lingo.dev] Failed to load dictionary:", error);
-      }
-    })();
-  }, []);
+  const locale = useMemo(() => getLocaleFromCookies(), []);
+  const resource = useMemo(
+    () =>
+      createDictionaryResource({
+        load: () => props.loadDictionary(locale),
+        locale,
+      }),
+    [props.loadDictionary, locale],
+  );
 
-  // TODO: handle case when the dictionary is loading (throw suspense?)
-  if (!dictionary) {
-    return null;
-  }
+  return (
+    <Suspense fallback={props.fallback}>
+      <DictionaryBoundary resource={resource}>
+        {props.children}
+      </DictionaryBoundary>
+    </Suspense>
+  );
+}
 
+function DictionaryBoundary<D>(props: {
+  resource: DictionaryResource<D>;
+  children: ReactNode;
+}) {
+  const dictionary = props.resource.read();
   return (
     <LingoProvider dictionary={dictionary}>{props.children}</LingoProvider>
   );
 }
+
+type DictionaryResource<D> = {
+  read(): D;
+};
+
+function createDictionaryResource<D>(options: {
+  load: () => Promise<D>;
+  locale: string | null;
+}): DictionaryResource<D> {
+  let status: "pending" | "success" | "error" = "pending";
+  let value: D;
+  let error: unknown;
+
+  const { locale } = options;
+  console.log(`[Lingo.dev] Loading dictionary file for locale ${locale}...`);
+
+  const suspender = options
+    .load()
+    .then((result) => {
+      value = result;
+      status = "success";
+      return result;
+    })
+    .catch((err) => {
+      console.log("[Lingo.dev] Failed to load dictionary:", err);
+      error = err;
+      status = "error";
+      throw err;
+    });
+
+  return {
+    read(): D {
+      if (status === "pending") {
+        throw suspender;
+      }
+      if (status === "error") {
+        throw error;
+      }
+      return value;
+    },
+  };
+}
+
+export function LingoProviderFallback() {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-busy="true"
+      className="lingo-provider-fallback"
+    >
+      Loading translations...
+    </div>
+  );
+}