@pylonsync/react 0.4.14 → 0.4.16

package/dist/dynamic.d.ts

@@ -0,0 +1,37 @@
+import React, { type ComponentType } from "react";
+export interface DynamicOptions {
+    /** Rendered while the chunk loads (and, when `ssr` is false, on the server). */
+    loading?: ComponentType<any> | null;
+    /**
+     * Render on the server as well as the client. Default **false**.
+     *
+     * This is the opposite of Next's default, and deliberately so. Under Pylon a
+     * page hydrates ONCE, after the whole document has streamed, so the safe
+     * contract is that the server HTML and the first client render are
+     * identical — which `ssr: false` guarantees by rendering the fallback in
+     * both. It is also the only mode that removes bytes from the first load: an
+     * `ssr: true` component has to be in the client bundle before hydration, so
+     * it saves nothing, and it's there for organizing code, not for weight.
+     */
+    ssr?: boolean;
+}
+type Loader<P> = () => Promise<{
+    default: ComponentType<P>;
+} | ComponentType<P>>;
+/**
+ * Defer a component into its own chunk.
+ *
+ * The returned component renders `loading` until the chunk arrives, then the
+ * real one. Call it at MODULE level, not inside a render — a `dynamic()` call
+ * per render creates a new component type each time and remounts the subtree.
+ *
+ * `ref` reaches the loaded component: React 19 treats it as an ordinary prop,
+ * so the spread carries it to a `forwardRef` target's imperative handle. That
+ * matters for the exact components people defer — an editor whose save path
+ * calls `ref.current.export()` would fail silently otherwise — so it's covered
+ * by a test rather than left to React's prop semantics staying put.
+ */
+export declare function dynamic<P extends object>(loader: Loader<P>, options?: DynamicOptions): ComponentType<P & {
+    ref?: React.Ref<any>;
+}>;
+export {};

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { defineRoute } from "@pylonsync/sdk";
 export type { RouteMode, AppManifest } from "@pylonsync/sdk";
 export { Link } from "./Link";
 export type { LinkProps } from "./Link";
+export { dynamic } from "./dynamic";
+export type { DynamicOptions } from "./dynamic";
 export { Image } from "./Image";
 export type { ImageProps } from "./Image";
 export { Form } from "./Form";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.14",
+  "version": "0.4.16",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.4.14",
-    "@pylonsync/sync": "0.4.14"
+    "@pylonsync/sdk": "0.4.16",
+    "@pylonsync/sync": "0.4.16"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/dynamic.test.tsx

@@ -0,0 +1,131 @@
+// Contract tests for dynamic() — component-level code splitting.
+//
+// The property that matters is that ssr:false cannot produce a hydration
+// mismatch. Pylon hydrates ONCE, after the whole document has streamed, so
+// the server HTML and the first client render must be identical. Rendering
+// the fallback in BOTH is what guarantees that; a component that appeared on
+// the first client pass would diverge from the server's markup.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+// react-dom/server ships no types in this workspace's resolution; the test
+// only needs one function from it.
+const { renderToStaticMarkup } = require("react-dom/server") as {
+  renderToStaticMarkup: (el: React.ReactElement) => string;
+};
+import React from "react";
+import { dynamic } from "./dynamic";
+
+// @testing-library auto-registers cleanup when it finds a global afterEach;
+// bun:test doesn't provide one, so mounted trees would accumulate across tests
+// in this file and queries would match components a later test never rendered.
+afterEach(cleanup);
+
+const Heavy = () => <div data-testid="heavy">heavy</div>;
+const Skeleton = () => <div data-testid="skeleton">loading…</div>;
+
+describe("dynamic() with ssr:false", () => {
+  test("server-renders the fallback, never the component", () => {
+    const D = dynamic(async () => ({ default: Heavy }), { loading: Skeleton });
+    const html = renderToStaticMarkup(<D />);
+    expect(html).toContain("loading…");
+    expect(html).not.toContain("heavy");
+  });
+
+  test("the FIRST client render matches the server's, then swaps", async () => {
+    // This is the anti-mismatch contract: identical first paint, real
+    // component only after an effect (which never runs during SSR).
+    const D = dynamic(async () => ({ default: Heavy }), { loading: Skeleton });
+    const html = renderToStaticMarkup(<D />);
+    const { container } = render(<D />);
+    expect(container.innerHTML).toBe(html);
+    await waitFor(() => expect(screen.getByTestId("heavy")).toBeDefined());
+  });
+
+  test("renders nothing rather than crashing when no fallback is given", () => {
+    const D = dynamic(async () => ({ default: Heavy }));
+    expect(renderToStaticMarkup(<D />)).toBe("");
+  });
+
+  test("passes props through to the loaded component", async () => {
+    const Greet = ({ name }: { name: string }) => <span data-testid="g">hi {name}</span>;
+    const D = dynamic(async () => ({ default: Greet }), { loading: Skeleton });
+    render(<D name="eric" />);
+    await waitFor(() => expect(screen.getByTestId("g").textContent).toBe("hi eric"));
+  });
+
+  test("accepts a module namespace or a bare component", async () => {
+    const D = dynamic(async () => Heavy as any, { loading: Skeleton });
+    render(<D />);
+    await waitFor(() => expect(screen.getByTestId("heavy")).toBeDefined());
+  });
+
+  test("loads the chunk once across multiple instances", async () => {
+    let calls = 0;
+    const D = dynamic(
+      async () => {
+        calls++;
+        return { default: Heavy };
+      },
+      { loading: Skeleton },
+    );
+    render(
+      <>
+        <D />
+        <D />
+        <D />
+      </>,
+    );
+    await waitFor(() => expect(screen.getAllByTestId("heavy")).toHaveLength(3));
+    expect(calls).toBe(1);
+  });
+
+  test("a failed chunk leaves the fallback up instead of blanking", async () => {
+    const orig = console.error;
+    console.error = () => {};
+    try {
+      const D = dynamic(async () => {
+        throw new Error("network");
+      }, { loading: Skeleton });
+      render(<D />);
+      await new Promise((r) => setTimeout(r, 20));
+      expect(screen.getByTestId("skeleton")).toBeDefined();
+    } finally {
+      console.error = orig;
+    }
+  });
+});
+
+describe("dynamic() with ssr:true", () => {
+  test("server-renders the real component", async () => {
+    const D = dynamic(async () => ({ default: Heavy }), {
+      ssr: true,
+      loading: Skeleton,
+    });
+    // React resolves lazy during a streaming server render; renderToStaticMarkup
+    // is sync, so drive it through the client renderer instead.
+    render(<D />);
+    await waitFor(() => expect(screen.getByTestId("heavy")).toBeDefined());
+  });
+});
+
+describe("dynamic() and refs", () => {
+  test("a ref reaches the loaded component's imperative handle", async () => {
+    // React 19 passes `ref` as an ordinary prop, so the spread carries it —
+    // but that's incidental enough to be worth pinning: a deferred editor
+    // whose save path calls ref.current.export() breaks silently otherwise.
+    const Editor = React.forwardRef<{ save: () => string }, { doc: string }>(
+      (props, ref) => {
+        React.useImperativeHandle(ref, () => ({ save: () => `saved:${props.doc}` }));
+        return <div data-testid="ed">{props.doc}</div>;
+      },
+    );
+    const D = dynamic<{ doc: string }>(async () => ({ default: Editor as any }), {
+      loading: Skeleton,
+    });
+    const ref = React.createRef<{ save: () => string }>();
+    render(<D doc="hello" ref={ref} />);
+    await waitFor(() => expect(screen.getByTestId("ed")).toBeDefined());
+    expect(ref.current?.save()).toBe("saved:hello");
+  });
+});

package/src/dynamic.tsx

@@ -0,0 +1,127 @@
+// Component-level code splitting — `next/dynamic` parity for Pylon.
+//
+// Route-level splitting gives every page its own entry chunk, which solves
+// having many routes. It does nothing for ONE route with a heavy dependency: a
+// page that statically imports a rich-text editor puts the whole editor in its
+// entry, and since <Link> warms sibling routes on sight, that weight lands on
+// the first load of every page in the section — for a component most visitors
+// never open.
+//
+// `dynamic()` moves it behind a real `import()`, which the bundler emits as
+// its own chunk and (deliberately) leaves out of the route's modulepreload
+// set, so the bytes ship only when something actually renders it.
+//
+//   const Editor = dynamic(() => import("./Editor"), {
+//     loading: () => <EditorSkeleton />,
+//   });
+//
+// NOTE the name collision, which is easy to misread: the route-segment export
+// `export const dynamic = "force-static" | "force-dynamic"` is a CACHE
+// directive and unrelated to this. Same word, different thing, both from Next.
+
+import React, {
+  Suspense,
+  lazy,
+  useEffect,
+  useState,
+  type ComponentType,
+} from "react";
+
+export interface DynamicOptions {
+  /** Rendered while the chunk loads (and, when `ssr` is false, on the server). */
+  loading?: ComponentType<any> | null;
+  /**
+   * Render on the server as well as the client. Default **false**.
+   *
+   * This is the opposite of Next's default, and deliberately so. Under Pylon a
+   * page hydrates ONCE, after the whole document has streamed, so the safe
+   * contract is that the server HTML and the first client render are
+   * identical — which `ssr: false` guarantees by rendering the fallback in
+   * both. It is also the only mode that removes bytes from the first load: an
+   * `ssr: true` component has to be in the client bundle before hydration, so
+   * it saves nothing, and it's there for organizing code, not for weight.
+   */
+  ssr?: boolean;
+}
+
+type Loader<P> = () => Promise<{ default: ComponentType<P> } | ComponentType<P>>;
+
+/** A module namespace or the component itself — accept both, like Next. */
+function resolveComponent<P>(
+  mod: { default: ComponentType<P> } | ComponentType<P>,
+): ComponentType<P> {
+  return (mod as { default: ComponentType<P> })?.default ?? (mod as ComponentType<P>);
+}
+
+/**
+ * Defer a component into its own chunk.
+ *
+ * The returned component renders `loading` until the chunk arrives, then the
+ * real one. Call it at MODULE level, not inside a render — a `dynamic()` call
+ * per render creates a new component type each time and remounts the subtree.
+ *
+ * `ref` reaches the loaded component: React 19 treats it as an ordinary prop,
+ * so the spread carries it to a `forwardRef` target's imperative handle. That
+ * matters for the exact components people defer — an editor whose save path
+ * calls `ref.current.export()` would fail silently otherwise — so it's covered
+ * by a test rather than left to React's prop semantics staying put.
+ */
+export function dynamic<P extends object>(
+  loader: Loader<P>,
+  options: DynamicOptions = {},
+): ComponentType<P & { ref?: React.Ref<any> }> {
+  const { loading: Loading = null, ssr = false } = options;
+
+  if (ssr) {
+    // Server-rendered: React awaits the lazy component during the SSR render,
+    // and Suspense covers the client while the chunk loads. No first-load
+    // saving — the component is in the tree the server rendered — so this is
+    // for splitting code, not weight.
+    const Lazy = lazy(async () => {
+      const mod = await loader();
+      return { default: resolveComponent<P>(mod) as ComponentType<any> };
+    });
+    const WithSuspense = (props: P) => (
+      <Suspense fallback={Loading ? <Loading /> : null}>
+        <Lazy {...(props as any)} />
+      </Suspense>
+    );
+    WithSuspense.displayName = "DynamicSSR";
+    return WithSuspense as ComponentType<P & { ref?: React.Ref<any> }>;
+  }
+
+  // Client-only. The fallback renders on the server AND on the first client
+  // pass, so the two agree byte for byte and hydration cannot mismatch; the
+  // real component swaps in from an effect, which never runs during SSR.
+  //
+  // The promise is cached on first use so remounts don't refetch, and so two
+  // instances of the same dynamic component share one request.
+  let cached: Promise<ComponentType<P>> | null = null;
+  const load = () => (cached ??= Promise.resolve(loader()).then(resolveComponent<P>));
+
+  const ClientOnly = (props: P) => {
+    const [Loaded, setLoaded] = useState<ComponentType<P> | null>(null);
+    useEffect(() => {
+      let alive = true;
+      load().then(
+        (C) => {
+          // The functional form — setState treats a bare function as an
+          // updater, and a component IS a function.
+          if (alive) setLoaded(() => C);
+        },
+        (err) => {
+          // A chunk that fails to load (deploy mid-session, offline) leaves
+          // the fallback up rather than blanking the subtree.
+          console.error("[pylon] dynamic() failed to load a component:", err);
+        },
+      );
+      return () => {
+        alive = false;
+      };
+    }, []);
+    if (!Loaded) return Loading ? <Loading /> : null;
+    return <Loaded {...(props as any)} />;
+  };
+  ClientOnly.displayName = "Dynamic";
+  return ClientOnly as ComponentType<P & { ref?: React.Ref<any> }>;
+}

package/src/index.ts

@@ -5,6 +5,8 @@ export type { RouteMode, AppManifest } from "@pylonsync/sdk";
 // progressively (work without JS) and enhance on the client.
 export { Link } from "./Link";
 export type { LinkProps } from "./Link";
+export { dynamic } from "./dynamic";
+export type { DynamicOptions } from "./dynamic";
 export { Image } from "./Image";
 export type { ImageProps } from "./Image";
 export { Form } from "./Form";