@tschk/moonshine-react 0.4.0 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tschk/moonshine-react",
-  "version": "0.4.0",
+  "version": "0.4.4",
   "description": "React renderer, islands, and signal hooks for Moonshine",
   "license": "ISC",
   "type": "module",
@@ -16,8 +16,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@tschk/moonshine": "^0.3.6",
-    "@tschk/moonshine-framework": "^0.3.6",
+    "@tschk/moonshine": "^0.4.4",
+    "@tschk/moonshine-framework": "^0.4.4",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },

package/src/islands.tsx

@@ -14,6 +14,7 @@ export type IslandEntry = {
   id: string;
   specifier: string;
   props: Record<string, unknown>;
+  hydrate?: "load" | "idle" | "visible";
 };
 
 export type IslandRegistry = {
@@ -21,6 +22,7 @@ export type IslandRegistry = {
 };
 
 const IslandContext = createContext<IslandRegistry | null>(null);
+const hydrationStates = new WeakMap<Element, { hydrated: boolean }>();
 
 const ISLAND_IMPORT_RE = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/;
 
@@ -54,8 +56,10 @@ export const IslandProvider: FunctionComponent<{
 
 export function island<P>(
   loader: () => Promise<ComponentType<P> | { default: ComponentType<P> }>,
+  options: { hydrate?: "load" | "idle" | "visible" } = {},
 ): FunctionComponent<P> {
-  const id = getIslandId(loader);
+  const hydrate = options.hydrate ?? "load";
+  const id = getIslandId(loader) + (hydrate === "load" ? "" : `-${hydrate}`);
   const specifier = extractSpecifier(loader);
   const IslandComponent: FunctionComponent<P> = (props) => {
     const registry = useContext(IslandContext);
@@ -71,12 +75,20 @@ export function island<P>(
         id,
         specifier,
         props: (props ?? {}) as Record<string, unknown>,
+        hydrate,
       });
     }
     return createElement(
       Fragment,
       null,
-      createElement("div", { "data-moonshine-island": id }, children),
+      createElement(
+        "div",
+        {
+          "data-moonshine-island": id,
+          "data-moonshine-hydrate": hydrate === "load" ? undefined : hydrate,
+        },
+        children,
+      ),
       createElement(
         "script",
         {
@@ -90,31 +102,88 @@ export function island<P>(
   return IslandComponent;
 }
 
-export function hydrateIslands(): void {
-  if (typeof document === "undefined") return;
+export function hydrateIslands(): () => void {
+  if (typeof document === "undefined") return () => {};
+  let disposed = false;
+  const cleanups: Array<() => void> = [];
   const modulesEl = document.querySelector(
     "script[data-moonshine-island-modules]",
   );
   const modules = modulesEl ? JSON.parse(modulesEl.textContent ?? "{}") : {};
   const markers = document.querySelectorAll("[data-moonshine-island]");
   for (const marker of Array.from(markers)) {
+    if (hydrationStates.has(marker)) continue;
     const id = marker.getAttribute("data-moonshine-island");
     if (!id) continue;
-    const propsEl = document.querySelector(
-      `script[data-moonshine-island-props="${id}"]`,
-    );
+    const sibling = marker.nextElementSibling;
+    const propsEl =
+      sibling?.getAttribute("data-moonshine-island-props") === id
+        ? sibling
+        : document.querySelector(`script[data-moonshine-island-props="${id}"]`);
     const props = propsEl ? JSON.parse(propsEl.textContent ?? "{}") : {};
     const specifier = modules[id];
     if (!specifier) continue;
-    import(specifier).then(async (mod) => {
-      const { hydrateRoot } = await import("react-dom/client");
-      const { createElement } = await import("react");
-      const Component = ((mod as { default?: ComponentType<unknown> })
-        .default ?? mod) as FunctionComponent<unknown>;
-      hydrateRoot(
-        marker,
-        createElement(Component, props as Record<string, unknown>),
-      );
+    const state = { hydrated: false };
+    hydrationStates.set(marker, state);
+    cleanups.push(() => {
+      if (!state.hydrated && hydrationStates.get(marker) === state)
+        hydrationStates.delete(marker);
     });
+    let started = false;
+    const hydrate = () => {
+      if (disposed || started || !marker.isConnected) return;
+      started = true;
+      return import(specifier)
+        .then(async (mod) => {
+          const client = await import("react-dom/client");
+          const { hydrateRoot } = client.default ?? client;
+          if (disposed || !marker.isConnected) return;
+          const Component = ((mod as { default?: ComponentType<unknown> })
+            .default ?? mod) as FunctionComponent<unknown>;
+          hydrateRoot(
+            marker,
+            createElement(Component, props as Record<string, unknown>),
+          );
+          state.hydrated = true;
+        })
+        .catch((error: unknown) => {
+          if (hydrationStates.get(marker) === state)
+            hydrationStates.delete(marker);
+          if (disposed) return;
+          if (typeof reportError === "function") reportError(error);
+          else console.error("Moonshine island hydration failed", error);
+        });
+    };
+    const mode = marker.getAttribute("data-moonshine-hydrate");
+    if (mode === "visible" && typeof IntersectionObserver !== "undefined") {
+      const observer = new IntersectionObserver((entries) => {
+        if (disposed || !entries.some((entry) => entry.isIntersecting)) return;
+        observer.disconnect();
+        void hydrate();
+      });
+      observer.observe(marker);
+      cleanups.push(() => observer.disconnect());
+    } else if (mode === "idle") {
+      if (typeof requestIdleCallback !== "undefined") {
+        const handle = requestIdleCallback(
+          () => {
+            if (!disposed) void hydrate();
+          },
+          { timeout: 2000 },
+        );
+        cleanups.push(() => cancelIdleCallback(handle));
+      } else {
+        const handle = setTimeout(() => {
+          if (!disposed) void hydrate();
+        }, 1);
+        cleanups.push(() => clearTimeout(handle));
+      }
+    } else {
+      void hydrate();
+    }
   }
+  return () => {
+    disposed = true;
+    for (const cleanup of cleanups) cleanup();
+  };
 }

package/src/renderer.tsx

@@ -78,7 +78,9 @@ function buildIslandHeadAndTail(
   const modules: Record<string, string> = {};
 
   for (const entry of registry.entries.values()) {
-    preloads.add(escapeHtml(entry.specifier));
+    if (entry.hydrate !== "idle" && entry.hydrate !== "visible") {
+      preloads.add(escapeHtml(entry.specifier));
+    }
     modules[entry.id] = entry.specifier;
   }
 
@@ -106,6 +108,10 @@ function buildIslandHeadAndTail(
   return { head: headParts.join(""), tail: tailParts.join("") };
 }
 
+/** Document shell matching crepuscularity CLI `assets/web/index.html`. */
+const DOCUMENT_HEAD =
+  '<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>html{scroll-behavior:smooth}html,body{margin:0}body{min-height:100vh}</style>';
+
 async function renderPage(context: RenderContext): Promise<string> {
   const registry: IslandRegistry = { entries: new Map() };
   const body = await buildBody(context, registry);
@@ -116,7 +122,7 @@ async function renderPage(context: RenderContext): Promise<string> {
     context.route.clientEntries,
     isIslandMode,
   );
-  return `<!DOCTYPE html><html><head>${head}</head><body>${bodyMarkup}${tail}</body></html>`;
+  return `<!DOCTYPE html><html lang="en"><head>${DOCUMENT_HEAD}${head}</head><body>${bodyMarkup}${tail}</body></html>`;
 }
 
 function renderSpaShell(context: RenderContext): string {
@@ -127,7 +133,7 @@ function renderSpaShell(context: RenderContext): string {
     head.push(`<link rel="modulepreload" href="${escapeHtml(entry)}">`);
     tail.push(`<script type="module" src="${escapeHtml(entry)}"></script>`);
   }
-  return `<!DOCTYPE html><html><head>${head.join("")}</head><body><div id="moonshine-app" data-moonshine-app="${escapeHtml(context.route.id)}"></div>${tail.join("")}</body></html>`;
+  return `<!DOCTYPE html><html lang="en"><head>${DOCUMENT_HEAD}${head.join("")}</head><body><div id="moonshine-app" data-moonshine-app="${escapeHtml(context.route.id)}"></div>${tail.join("")}</body></html>`;
 }
 
 export const reactRenderer: Renderer = {