catalyst-core 0.3.0-beta.4 → 0.3.0-canary.1

package/dist/web-router/components/Split.jsx

@@ -1,17 +1,32 @@
-import React, { Suspense, lazy, useContext, useEffect, useReducer } from "react"
-import { SsrRequestContext } from "./SsrRequestContext.jsx"
-import SplitInview from "./SplitInview.jsx"
+import React, { Suspense, lazy, useContext, useEffect, useReducer } from "react";
+import { SsrRequestContext } from "./SsrRequestContext.jsx";
+import SplitInview from "./SplitInview.jsx";
+
+/**
+ * A dynamic import of a module whose default export is the component to split.
+ * Matches the argument React's `lazy` accepts.
+ */
+
+/**
+ * Options accepted by {@link split}.
+ */
+
+/**
+ * The component returned by {@link split}. It renders the lazily imported
+ * component and additionally carries the route statics copied off the loaded
+ * module, plus `load()` for the fetcher contract RouterDataProvider relies on.
+ */
 
 // Synchronous module cache: importFn → resolved module.
 // Populated by the eager importFn().then() calls at split() invocation time.
 // By the time window.load fires (when hydrateRoot runs), all chunk <script>
 // tags in the HTML have already executed, so every .then() has already
 // resolved and the module is available here synchronously.
-const moduleCache = new Map()
+const moduleCache = new Map();
 
 // Collects one promise per SSR-rendered split() call on the client.
 // loadableReady() waits for all of them before hydration begins.
-const prefetchPromises = []
+const prefetchPromises = [];
 
 /**
  * Returns a promise that resolves once every SSR-rendered split component
@@ -24,58 +39,55 @@ const prefetchPromises = []
  *   hydrateRoot(document.getElementById("root"), <App />)
  * })
  */
-export const hydrationReady = () => Promise.all(prefetchPromises)
+export const hydrationReady = () => Promise.all(prefetchPromises);
+
+/**
+ * Props for the internal Split wrapper. `split()` is the public entry point;
+ * this component is an implementation detail of it.
+ */
 
 /**
  * Split component that wraps React's lazy and Suspense for SSR compatibility
- * @param {Object} props
- * @param {boolean} props.ssr - Whether to render the component on the server
- * @param {React.ComponentType|React.ReactElement} props.fallback - Fallback component for loading state
- * @param {Function} props.children - Function that returns the lazy component import
- * @param {string} props.cacheKey - Resolved path for better asset tracking
  */
 const Split = ({
-    ssr = true,
-    fallback = null,
-    cacheKey,
-    rootOptions,
-    onVisible,
-    skipVisibility,
-    children,
+  ssr = true,
+  fallback = null,
+  cacheKey,
+  rootOptions,
+  onVisible,
+  skipVisibility,
+  children
 }) => {
-    // Check if we're on the server
-    const isServer = typeof window === "undefined"
-    if (isServer) {
-        if (ssr) {
-            // On server with SSR enabled: actually load and render the component
-            try {
-                // Track this component for asset extraction
-                if (global.__CHUNK_EXTRACTOR__) {
-                    global.__CHUNK_EXTRACTOR__.addComponent(cacheKey)
-                }
-
-                return <Suspense fallback={fallback}>{children}</Suspense>
-            } catch (error) {
-                console.warn("Error loading component for SSR:", error)
-                return fallback
-            }
-        } else {
-            // Match SplitInview's client-side wrapper so hydration doesn't mismatch.
-            // SplitInview renders <div ref>{fallback}</div> until visible; without this
-            // wrap, server outputs `fallback` and client outputs `<div>{fallback}</div>`.
-            return <div>{fallback}</div>
+  // Check if we're on the server
+  const isServer = typeof window === "undefined";
+  if (isServer) {
+    if (ssr) {
+      // On server with SSR enabled: actually load and render the component
+      try {
+        // Track this component for asset extraction
+        if (global.__CHUNK_EXTRACTOR__) {
+          global.__CHUNK_EXTRACTOR__.addComponent(cacheKey);
         }
+        return <Suspense fallback={fallback}>{children}</Suspense>;
+      } catch (error) {
+        console.warn("Error loading component for SSR:", error);
+        return fallback;
+      }
     } else {
-        if (skipVisibility) {
-            return <Suspense fallback={fallback}>{children}</Suspense>
-        }
-        return (
-            <SplitInview fallback={fallback} rootOptions={rootOptions} onVisible={onVisible}>
-                <Suspense fallback={fallback}>{children}</Suspense>
-            </SplitInview>
-        )
+      // Match SplitInview's client-side wrapper so hydration doesn't mismatch.
+      // SplitInview renders <div ref>{fallback}</div> until visible; without this
+      // wrap, server outputs `fallback` and client outputs `<div>{fallback}</div>`.
+      return <div>{fallback}</div>;
     }
-}
+  } else {
+    if (skipVisibility) {
+      return <Suspense fallback={fallback}>{children}</Suspense>;
+    }
+    return <SplitInview fallback={fallback} rootOptions={rootOptions} onVisible={onVisible}>
+                <Suspense fallback={fallback}>{children}</Suspense>
+            </SplitInview>;
+  }
+};
 
 /**
  * Like {@link split}, but forces SSR when the request is a known Google crawler (same UA rules as Head).
@@ -85,116 +97,95 @@ const Split = ({
  * still hydrates without a Suspense flash.
  */
 export const split = (importFn, options = {}, thirdArg, fourthArg) => {
-    const { ssr = true, fallback = null } = options || {}
-    const hasThirdArg = typeof thirdArg !== "undefined"
-    const hasFourthArg = typeof fourthArg !== "undefined"
-    const cacheKey =
-        typeof fourthArg === "string" ? fourthArg : typeof thirdArg === "string" ? thirdArg : undefined
-    const rootOptions = hasFourthArg
-        ? thirdArg
-        : hasThirdArg && typeof thirdArg !== "string"
-          ? thirdArg
-          : undefined
-
-    const LazyComponent = lazy(importFn)
-    let loadInFlight = null
-
-    // Per-split instance subscribers. Pending wrapper instances register their
-    // forceUpdate here; notifyAll() wakes them when load() resolves or any
-    // sibling becomes visible, so they can re-render against the now-hot cache
-    // or skip their own observer setup.
-    const subscribers = new Set()
-    let anyVisible = false
-    const notifyAll = () => {
-        anyVisible = true
-        subscribers.forEach((fn) => fn())
-    }
-    const copyRouteStatics = (mod) => {
-        const Component = mod?.default || mod
-        for (const key of ["clientFetcher", "serverFetcher", "setMetaData"]) {
-            if (Component?.[key]) wrapper[key] = Component[key]
-        }
-        return mod
-    }
-
-    if (typeof window !== "undefined" && window.__SSR_RENDERED_COMPONENTS__?.has(cacheKey)) {
-        const prefetch = importFn().then((mod) => {
-            moduleCache.set(importFn, mod)
-            copyRouteStatics(mod)
-        })
-        prefetchPromises.push(prefetch)
+  const {
+    ssr = true,
+    fallback = null
+  } = options || {};
+  const hasThirdArg = typeof thirdArg !== "undefined";
+  const hasFourthArg = typeof fourthArg !== "undefined";
+  const cacheKey = typeof fourthArg === "string" ? fourthArg : typeof thirdArg === "string" ? thirdArg : undefined;
+  const rootOptions = hasFourthArg ? thirdArg : hasThirdArg && typeof thirdArg !== "string" ? thirdArg : undefined;
+  const LazyComponent = lazy(importFn);
+  let loadInFlight = null;
+
+  // Per-split instance subscribers. Pending wrapper instances register their
+  // forceUpdate here; notifyAll() wakes them when load() resolves or any
+  // sibling becomes visible, so they can re-render against the now-hot cache
+  // or skip their own observer setup.
+  const subscribers = new Set();
+  let anyVisible = false;
+  const notifyAll = () => {
+    anyVisible = true;
+    subscribers.forEach(fn => fn());
+  };
+  const copyRouteStatics = mod => {
+    const Component = mod?.default || mod;
+    for (const key of ["clientFetcher", "serverFetcher", "setMetaData"]) {
+      if (Component?.[key]) wrapper[key] = Component[key];
     }
-
-    const wrapper = ({ fallback: fallbackProp, ...props }) => {
-        const { isBot: isBotFromContext } = useContext(SsrRequestContext)
-        const isBotFromWindow = typeof window !== "undefined" && window.__CATALYST_IS_BOT__ === true
-        const isBot = Boolean(isBotFromContext || isBotFromWindow)
-        const effectiveSsr = ssr || isBot
-        const effectiveFallback = fallbackProp !== undefined ? fallbackProp : fallback
-
-        const [, forceUpdate] = useReducer((x) => x + 1, 0)
-        useEffect(() => {
-            subscribers.add(forceUpdate)
-            return () => {
-                subscribers.delete(forceUpdate)
-            }
-        }, [])
-
-        const mod = moduleCache.get(importFn)
-        if (mod) {
-            const Component = mod.default || mod
-            return (
-                <Suspense fallback={effectiveFallback}>
+    return mod;
+  };
+  if (typeof window !== "undefined" && window.__SSR_RENDERED_COMPONENTS__?.has(cacheKey)) {
+    const prefetch = importFn().then(mod => {
+      moduleCache.set(importFn, mod);
+      copyRouteStatics(mod);
+    });
+    prefetchPromises.push(prefetch);
+  }
+  const wrapper = ({
+    fallback: fallbackProp,
+    ...props
+  }) => {
+    const {
+      isBot: isBotFromContext
+    } = useContext(SsrRequestContext);
+    const isBotFromWindow = typeof window !== "undefined" && window.__CATALYST_IS_BOT__ === true;
+    const isBot = Boolean(isBotFromContext || isBotFromWindow);
+    const effectiveSsr = ssr || isBot;
+    const effectiveFallback = fallbackProp !== undefined ? fallbackProp : fallback;
+    const [, forceUpdate] = useReducer(x => x + 1, 0);
+    useEffect(() => {
+      subscribers.add(forceUpdate);
+      return () => {
+        subscribers.delete(forceUpdate);
+      };
+    }, []);
+    const mod = moduleCache.get(importFn);
+    if (mod) {
+      const Component = mod.default || mod;
+      return <Suspense fallback={effectiveFallback}>
                     <Component {...props} />
-                </Suspense>
-            )
-        }
-
-        return (
-            <Split
-                ssr={effectiveSsr}
-                fallback={effectiveFallback}
-                cacheKey={cacheKey}
-                rootOptions={rootOptions}
-                onVisible={() => {
-                    notifyAll()
-                    props.onVisible?.()
-                }}
-                skipVisibility={effectiveSsr || anyVisible}
-                {...props}
-                isBot={isBot}
-            >
-                <LazyComponent {...props} />
-            </Split>
-        )
+                </Suspense>;
     }
-
-    wrapper.__cacheKey = cacheKey
-
-    /** Same contract as loadable components: RouterDataProvider awaits this before reading serverFetcher/clientFetcher. */
-    wrapper.load = () => {
-        const cached = moduleCache.get(importFn)
-        if (cached) return Promise.resolve(cached)
-        if (!loadInFlight) {
-            loadInFlight = importFn()
-                .then((mod) => {
-                    copyRouteStatics(mod)
-                    if (typeof window !== "undefined") {
-                        moduleCache.set(importFn, mod)
-                    }
-                    loadInFlight = null
-                    notifyAll()
-                    return mod
-                })
-                .catch((err) => {
-                    loadInFlight = null
-                    throw err
-                })
+    return <Split ssr={effectiveSsr} fallback={effectiveFallback} cacheKey={cacheKey} rootOptions={rootOptions} onVisible={() => {
+      notifyAll();
+      props.onVisible?.();
+    }} skipVisibility={effectiveSsr || anyVisible} {...props} isBot={isBot}>
+                <LazyComponent {...props} />
+            </Split>;
+  };
+  wrapper.__cacheKey = cacheKey;
+
+  /** Same contract as loadable components: RouterDataProvider awaits this before reading serverFetcher/clientFetcher. */
+  wrapper.load = () => {
+    const cached = moduleCache.get(importFn);
+    if (cached) return Promise.resolve(cached);
+    if (!loadInFlight) {
+      loadInFlight = importFn().then(mod => {
+        copyRouteStatics(mod);
+        if (typeof window !== "undefined") {
+          moduleCache.set(importFn, mod);
         }
-        return loadInFlight
+        loadInFlight = null;
+        notifyAll();
+        return mod;
+      }).catch(err => {
+        loadInFlight = null;
+        throw err;
+      });
     }
-
-    return wrapper
-}
-
-export default Split
+    return loadInFlight;
+  };
+  return wrapper;
+};
+export default Split;

package/dist/web-router/components/Split.server.test.jsx

@@ -0,0 +1,52 @@
+// @vitest-environment node
+//
+// Server-side Split coverage (#347/#348-style split). The jsdom
+// Split.test.jsx cannot reach these branches -- Split checks
+// `typeof window === "undefined"` and jsdom always defines window. Routed
+// to the "node" project by the *.server.test.* include/exclude split in
+// vitest.config.ts.
+
+import React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import Split from "./Split.jsx"
+
+afterEach(() => {
+    delete global.__CHUNK_EXTRACTOR__
+    vi.restoreAllMocks()
+})
+
+describe("Split (server)", () => {
+    it("with ssr enabled: registers the component with the chunk extractor and renders children in Suspense", () => {
+        const addComponent = vi.fn()
+        global.__CHUNK_EXTRACTOR__ = { addComponent }
+
+        const html = renderToStaticMarkup(
+            <Split ssr cacheKey="pages/Widget" fallback={<span>fallback</span>}>
+                <p>real child</p>
+            </Split>,
+        )
+
+        expect(addComponent).toHaveBeenCalledWith("pages/Widget")
+        expect(html).toContain("real child")
+    })
+
+    it("with ssr enabled and no chunk extractor present: still renders children (no throw)", () => {
+        const html = renderToStaticMarkup(
+            <Split ssr cacheKey="pages/NoExtractor">
+                <p>child ok</p>
+            </Split>,
+        )
+        expect(html).toContain("child ok")
+    })
+
+    it("with ssr disabled: renders the fallback wrapped in a <div> to match the client hydration shape", () => {
+        const html = renderToStaticMarkup(
+            <Split ssr={false} cacheKey="pages/Deferred" fallback={<span>loading…</span>}>
+                <p>should not appear</p>
+            </Split>,
+        )
+        expect(html).toBe("<div><span>loading…</span></div>")
+        expect(html).not.toContain("should not appear")
+    })
+})

package/dist/web-router/components/Split.test.jsx

@@ -0,0 +1,167 @@
+import React, { Suspense } from "react"
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest"
+import { render, screen, waitFor, act } from "@testing-library/react"
+import Split, { split } from "./Split.jsx"
+import { SsrRequestProvider } from "./SsrRequestContext.jsx"
+
+// jsdom does not implement IntersectionObserver; SplitInview (used by the
+// client, non-skipVisibility path) needs one. Stub it to fire visible
+// immediately so tests default to "already visible" unless a test wants
+// to hold back visibility deliberately.
+class ImmediateIntersectionObserver {
+    constructor(callback) {
+        this.callback = callback
+    }
+    observe(node) {
+        // Fire on next tick so React has committed the ref first.
+        Promise.resolve().then(() => this.callback([{ target: node, isIntersecting: true }]))
+    }
+    unobserve() {}
+    disconnect() {}
+}
+
+beforeEach(() => {
+    vi.stubGlobal("IntersectionObserver", ImmediateIntersectionObserver)
+})
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+})
+
+describe("Split (client-side, window defined)", () => {
+    it("renders children directly when skipVisibility is true", () => {
+        render(
+            <Split skipVisibility fallback={<span>loading</span>}>
+                <span>content</span>
+            </Split>
+        )
+        expect(screen.getByText("content")).toBeInTheDocument()
+    })
+
+    it("defers to SplitInview (shows fallback first) when skipVisibility is false", () => {
+        render(
+            <Split fallback={<span>loading</span>}>
+                <span>content</span>
+            </Split>
+        )
+        // Before the stubbed IntersectionObserver's microtask fires,
+        // SplitInview should still be showing the fallback.
+        expect(screen.getByText("loading")).toBeInTheDocument()
+    })
+
+    it("eventually renders children once SplitInview reports visibility", async () => {
+        render(
+            <Split fallback={<span>loading</span>}>
+                <span>content</span>
+            </Split>
+        )
+        await waitFor(() => expect(screen.getByText("content")).toBeInTheDocument())
+    })
+})
+
+describe("split()", () => {
+    it("returns a component (wrapper) rather than throwing, given a lazy-style import function", () => {
+        const importFn = () => Promise.resolve({ default: () => <span>lazy content</span> })
+        const LazyThing = split(importFn, { ssr: false })
+        expect(typeof LazyThing).toBe("function")
+        expect(typeof LazyThing.load).toBe("function")
+    })
+
+    it("eventually renders the resolved component's output", async () => {
+        const importFn = () => Promise.resolve({ default: () => <span>lazy content</span> })
+        const LazyThing = split(importFn, { ssr: false, fallback: <span>loading</span> })
+        render(<LazyThing skipVisibility />)
+        await waitFor(() => expect(screen.getByText("lazy content")).toBeInTheDocument())
+    })
+
+    it("copies clientFetcher/serverFetcher/setMetaData from the resolved module onto the wrapper via load()", async () => {
+        const clientFetcher = vi.fn()
+        const serverFetcher = vi.fn()
+        const setMetaData = vi.fn()
+        const importFn = () =>
+            Promise.resolve({
+                default: Object.assign(() => <span>x</span>, { clientFetcher, serverFetcher, setMetaData }),
+            })
+        const LazyThing = split(importFn, {})
+        await LazyThing.load()
+        expect(LazyThing.clientFetcher).toBe(clientFetcher)
+        expect(LazyThing.serverFetcher).toBe(serverFetcher)
+        expect(LazyThing.setMetaData).toBe(setMetaData)
+    })
+
+    it("load() only calls the import function once even when called multiple times concurrently", async () => {
+        const importFn = vi.fn().mockResolvedValue({ default: () => <span>x</span> })
+        const LazyThing = split(importFn, {})
+        const [a, b] = await Promise.all([LazyThing.load(), LazyThing.load()])
+        expect(importFn).toHaveBeenCalledTimes(1)
+        expect(a).toBe(b)
+    })
+
+    it("load() caches its result -- a second call after resolution reuses the cached module without re-importing", async () => {
+        const importFn = vi.fn().mockResolvedValue({ default: () => <span>x</span> })
+        const LazyThing = split(importFn, {})
+        await LazyThing.load()
+        await LazyThing.load()
+        expect(importFn).toHaveBeenCalledTimes(1)
+    })
+
+    it("load() clears the in-flight promise and rethrows when the import rejects", async () => {
+        const importFn = vi.fn().mockRejectedValue(new Error("chunk 404"))
+        const LazyThing = split(importFn, {})
+        await expect(LazyThing.load()).rejects.toThrow("chunk 404")
+        // in-flight was cleared -> a retry re-imports rather than
+        // returning the settled rejection.
+        importFn.mockResolvedValueOnce({ default: () => <span>recovered</span> })
+        await expect(LazyThing.load()).resolves.toBeTruthy()
+        expect(importFn).toHaveBeenCalledTimes(2)
+    })
+
+    it("copies clientFetcher / serverFetcher / setMetaData statics onto the wrapper after load()", async () => {
+        const clientFetcher = () => {}
+        const setMetaData = () => {}
+        const importFn = vi
+            .fn()
+            .mockResolvedValue({ default: Object.assign(() => <span>c</span>, { clientFetcher, setMetaData }) })
+        const LazyThing = split(importFn, {})
+        await LazyThing.load()
+        expect(LazyThing.clientFetcher).toBe(clientFetcher)
+        expect(LazyThing.setMetaData).toBe(setMetaData)
+    })
+
+    it("renders straight from the module cache (no Split/observer) once load() has resolved", async () => {
+        const importFn = vi.fn().mockResolvedValue({ default: () => <span>from cache</span> })
+        const LazyThing = split(importFn, { ssr: false })
+        await LazyThing.load()
+        render(<LazyThing />)
+        await waitFor(() => expect(screen.getByText("from cache")).toBeInTheDocument())
+    })
+
+    it("prefetches when window.__SSR_RENDERED_COMPONENTS__ already contains the cacheKey", async () => {
+        const prev = window.__SSR_RENDERED_COMPONENTS__
+        window.__SSR_RENDERED_COMPONENTS__ = new Set(["pages/Prefetched"])
+        try {
+            const importFn = vi.fn().mockResolvedValue({ default: () => <span>pf</span> })
+            split(importFn, {}, undefined, "pages/Prefetched")
+            // the constructor-time prefetch fired
+            await waitFor(() => expect(importFn).toHaveBeenCalled())
+        } finally {
+            window.__SSR_RENDERED_COMPONENTS__ = prev
+        }
+    })
+
+    it("treats a bot request (via SsrRequestContext) as forcing effectiveSsr, skipping visibility gating", async () => {
+        const importFn = () => Promise.resolve({ default: () => <span>bot content</span> })
+        const LazyThing = split(importFn, { ssr: false })
+        render(
+            <SsrRequestProvider value={{ isBot: true }}>
+                <LazyThing />
+            </SsrRequestProvider>
+        )
+        // effectiveSsr = ssr || isBot = false || true = true, so Split's
+        // `!isServer` branch takes skipVisibility={effectiveSsr || anyVisible}
+        // = true -- content should render without waiting on an
+        // IntersectionObserver callback at all.
+        await waitFor(() => expect(screen.getByText("bot content")).toBeInTheDocument())
+    })
+})

package/dist/web-router/components/SplitInview.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Props for the internal visibility-deferring wrapper. Not part of the public
+ * surface: `split()` supplies these from its own options.
+ */
+interface SplitInviewProps {
+    /** Shown while the component is outside the viewport */
+    fallback?: any;
+    /** Rendered once the placeholder scrolls into view */
+    children?: any;
+    /** Optional IntersectionObserver options for parity with react-loadable-visibility */
+    rootOptions?: any;
+    /** Called once when the placeholder enters the viewport */
+    onVisible?: () => void;
+}
+/**
+ * Defers rendering of children until the placeholder enters the viewport.
+ * Once visible, it stays visible.
+ *
+ * On the server or when IntersectionObserver is unavailable, children render immediately.
+ */
+declare const SplitInview: ({ fallback, children, rootOptions, onVisible }: SplitInviewProps) => any;
+export default SplitInview;