@tschk/moonshine-react 0.3.1

package/README.md

@@ -0,0 +1,20 @@
+# `@tschk/moonshine-react`
+
+React renderer, islands, hydration, and signal hooks for Moonshine.
+
+```ts
+import { createApp, useSignal, createSignal } from "@tschk/moonshine-react";
+import { island, hydrateIslands } from "@tschk/moonshine-react";
+```
+
+Features:
+
+- `reactRenderer` implements the `Renderer` contract for SSR and streaming.
+- `island` / `hydrateIslands` for partial hydration.
+- `createApp`, `useSignal`, `useResource`, `createIslandSignal`.
+- `serializeIslandProps` for server island props.
+
+Peer dependencies: `react` and `react-dom` >= 18.
+
+See [docs/MANIFEST.md](../../docs/MANIFEST.md) and
+[DESIGN.md](../../DESIGN.md).

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tschk/moonshine-react",
+  "version": "0.3.1",
+  "description": "React renderer, islands, and signal hooks for Moonshine",
+  "license": "ISC",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "format": "bunx prettier --check .",
+    "lint": "bunx oxlint .",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@tschk/moonshine": "^0.3.1",
+    "@tschk/moonshine-framework": "^0.3.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "typescript": "7.0.2"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "moonshine",
+    "react",
+    "renderer",
+    "islands",
+    "signals"
+  ]
+}

package/src/client.tsx

@@ -0,0 +1,158 @@
+import {
+  createElement,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+  batch,
+  createMemo,
+  createSignal,
+  createStore,
+  getStoreRoot,
+  untrack,
+  type Memo,
+  type Signal,
+  type StoreSetter,
+} from "@tschk/moonshine";
+import {
+  createResource,
+  type CreateResourceOptions,
+  type Resource,
+  type ResourceStatus,
+} from "@tschk/moonshine";
+
+export type MoonshineAppOptions = {
+  root: ComponentType;
+  className?: string;
+};
+
+export type MoonshineApp = {
+  mount: (container: string | Element) => void;
+  unmount: () => void;
+  readonly mounted: boolean;
+};
+
+export function createMoonshineApp(options: MoonshineAppOptions): MoonshineApp {
+  let reactRoot: Root | null = null;
+  let host: Element | null = null;
+  let mounted = false;
+
+  return {
+    get mounted() {
+      return mounted;
+    },
+    mount(container) {
+      if (mounted) {
+        throw new Error("createMoonshineApp: already mounted");
+      }
+
+      const el =
+        typeof container === "string"
+          ? document.querySelector(container)
+          : container;
+      if (!el) {
+        throw new Error(
+          `createMoonshineApp: mount target not found: ${String(container)}`,
+        );
+      }
+
+      host = el;
+      if (options.className) {
+        el.classList.add(...options.className.split(/\s+/).filter(Boolean));
+      }
+
+      reactRoot = createRoot(el);
+      reactRoot.render(<options.root />);
+      mounted = true;
+    },
+    unmount() {
+      if (!mounted || !reactRoot) return;
+      reactRoot.unmount();
+      reactRoot = null;
+      if (host && options.className) {
+        for (const cls of options.className.split(/\s+/).filter(Boolean)) {
+          host.classList.remove(cls);
+        }
+      }
+      host = null;
+      mounted = false;
+    },
+  };
+}
+
+export const createApp = createMoonshineApp;
+
+type Subscribable<T> = (() => T) & {
+  subscribe: (listener: () => void) => () => void;
+  peek?: () => T;
+};
+
+export function useSignal<T>(
+  source: Subscribable<T>,
+  getServerSnapshot?: () => T,
+): T {
+  const subscribe = (onStoreChange: () => void) =>
+    source.subscribe(onStoreChange);
+  const getSnapshot = () => source();
+  const server =
+    getServerSnapshot ??
+    (() =>
+      typeof source.peek === "function"
+        ? (source.peek as () => T)()
+        : source());
+  return useSyncExternalStore(subscribe, getSnapshot, server);
+}
+
+export function useStore<T extends object>(store: T): T {
+  const node = getStoreRoot(store as object);
+  if (!node) {
+    throw new Error("useStore: expected a createStore() proxy");
+  }
+  useSyncExternalStore(
+    node.subscribe,
+    () => store,
+    () => store,
+  );
+  return store;
+}
+
+export function useResource<T>(resource: Resource<T>): {
+  data: T | undefined;
+  loading: boolean;
+  error: Error | undefined;
+  status: ReturnType<Resource<T>["status"]>;
+  refetch: () => Promise<T | undefined>;
+} {
+  const data = useSignal(resource);
+  const loading = useSignal(resource.loading);
+  const error = useSignal(resource.error);
+  const status = useSignal(resource.status);
+  return { data, loading, error, status, refetch: resource.refetch };
+}
+
+export function createIslandSignal<T>(initial: T): Signal<T> {
+  return createSignal(initial);
+}
+
+export function renderToNode(root: ComponentType): ReactNode {
+  return createElement(root);
+}
+
+export {
+  batch,
+  createMemo,
+  createResource,
+  createSignal,
+  createStore,
+  untrack,
+};
+export type {
+  CreateResourceOptions,
+  Memo,
+  Resource,
+  ResourceStatus,
+  Signal,
+  StoreSetter,
+};

package/src/index.ts

@@ -0,0 +1,30 @@
+export { reactRenderer } from "./renderer";
+export type { RenderContext, Renderer } from "@tschk/moonshine-framework";
+export {
+  batch,
+  createApp,
+  createIslandSignal,
+  createMemo,
+  createMoonshineApp,
+  createResource,
+  createSignal,
+  createStore,
+  renderToNode,
+  untrack,
+  useResource,
+  useSignal,
+  useStore,
+} from "./client";
+export type {
+  CreateResourceOptions,
+  Memo,
+  MoonshineApp,
+  MoonshineAppOptions,
+  Resource,
+  ResourceStatus,
+  Signal,
+  StoreSetter,
+} from "./client";
+export { island, hydrateIslands } from "./islands";
+export type { IslandEntry, IslandRegistry } from "./islands";
+export { serializeIslandProps } from "./serialize";

package/src/islands.tsx

@@ -0,0 +1,113 @@
+import {
+  createContext,
+  createElement,
+  Fragment,
+  use,
+  useContext,
+  type ComponentType,
+  type FunctionComponent,
+  type ReactNode,
+} from "react";
+import { serializeIslandProps } from "./serialize";
+
+export type IslandEntry = {
+  id: string;
+  specifier: string;
+  props: Record<string, unknown>;
+};
+
+export type IslandRegistry = {
+  entries: Map<string, IslandEntry>;
+};
+
+const IslandContext = createContext<IslandRegistry | null>(null);
+
+const ISLAND_IMPORT_RE = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/;
+
+function extractSpecifier(loader: () => Promise<unknown>): string {
+  const source = loader.toString();
+  const match = source.match(ISLAND_IMPORT_RE);
+  return match ? match[1]! : source;
+}
+
+function hashString(input: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash +=
+      (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+    hash >>>= 0;
+  }
+  return hash.toString(36);
+}
+
+function getIslandId(loader: () => Promise<unknown>): string {
+  return `moonshine-island-${hashString(extractSpecifier(loader))}`;
+}
+
+export const IslandProvider: FunctionComponent<{
+  registry: IslandRegistry;
+  children?: ReactNode;
+}> = ({ registry, children }) => {
+  return createElement(IslandContext.Provider, { value: registry }, children);
+};
+
+export function island<P>(
+  loader: () => Promise<ComponentType<P> | { default: ComponentType<P> }>,
+): FunctionComponent<P> {
+  const id = getIslandId(loader);
+  const specifier = extractSpecifier(loader);
+  const IslandComponent: FunctionComponent<P> = (props) => {
+    const registry = useContext(IslandContext);
+    const mod = use(loader());
+    const Component = ((mod as { default?: ComponentType<P> }).default ??
+      mod) as FunctionComponent<P>;
+    const children = createElement(Component as any, props as any);
+    if (registry) {
+      registry.entries.set(id, {
+        id,
+        specifier,
+        props: (props ?? {}) as Record<string, unknown>,
+      });
+    }
+    return createElement(
+      Fragment,
+      null,
+      createElement("div", { "data-moonshine-island": id }, children),
+      createElement("script", {
+        type: "application/json",
+        "data-moonshine-island-props": id,
+        dangerouslySetInnerHTML: {
+          __html: serializeIslandProps(props),
+        },
+      }),
+    );
+  };
+  return IslandComponent;
+}
+
+export function hydrateIslands(): void {
+  if (typeof document === "undefined") return;
+  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)) {
+    const id = marker.getAttribute("data-moonshine-island");
+    if (!id) continue;
+    const propsEl = 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 as any, props as any));
+    });
+  }
+}

package/src/renderer.tsx

@@ -0,0 +1,147 @@
+import {
+  createElement,
+  type ComponentType,
+  type FunctionComponent,
+  type ReactNode,
+} from "react";
+import { renderToReadableStream } from "react-dom/server";
+import type { RenderContext, Renderer } from "@tschk/moonshine-framework";
+import { IslandProvider, type IslandRegistry } from "./islands";
+import { escapeHtml, serializeIslandProps } from "./serialize";
+
+async function renderToStringAsync(
+  element: ReactNode,
+  signal?: AbortSignal,
+): Promise<string> {
+  const stream = await renderToReadableStream(element, { signal });
+  await stream.allReady;
+  const res = new Response(stream);
+  return res.text();
+}
+
+type PageProps = {
+  params: Record<string, string>;
+  data: unknown;
+};
+
+type LayoutProps = PageProps & {
+  children?: ReactNode;
+};
+
+async function loadComponent(file: string): Promise<ComponentType<unknown>> {
+  const mod = await import(file);
+  return (mod.default ?? mod) as ComponentType<unknown>;
+}
+
+async function buildBody(
+  context: RenderContext,
+  registry: IslandRegistry,
+): Promise<ReactNode> {
+  const { route, params, data } = context;
+  const Page = (await loadComponent(
+    route.file,
+  )) as FunctionComponent<PageProps>;
+  const pageProps = { params, data };
+  let body = createElement(Page, pageProps);
+
+  if (route.layouts) {
+    for (let i = route.layouts.length - 1; i >= 0; i--) {
+      const Layout = (await loadComponent(
+        route.layouts[i]!,
+      )) as FunctionComponent<LayoutProps>;
+      body = createElement(Layout, { ...pageProps, children: body });
+    }
+  }
+
+  return createElement(IslandProvider, { registry }, body);
+}
+
+function buildIslandHeadAndTail(
+  registry: IslandRegistry,
+  clientEntries: string[],
+  isIslandMode: boolean,
+): { head: string; tail: string } {
+  const preloads = new Set<string>();
+  const modules: Record<string, string> = {};
+
+  for (const entry of registry.entries.values()) {
+    preloads.add(escapeHtml(entry.specifier));
+    modules[entry.id] = entry.specifier;
+  }
+
+  const headParts: string[] = [];
+  for (const href of preloads) {
+    headParts.push(`<link rel="modulepreload" href="${href}">`);
+  }
+
+  const tailParts: string[] = [];
+  if (isIslandMode && registry.entries.size > 0) {
+    for (const entry of clientEntries) {
+      preloads.add(escapeHtml(entry));
+      headParts.push(`<link rel="modulepreload" href="${escapeHtml(entry)}">`);
+    }
+    tailParts.push(
+      `<script type="application/json" data-moonshine-island-modules>${serializeIslandProps(modules)}</script>`,
+    );
+    for (const entry of clientEntries) {
+      tailParts.push(
+        `<script type="module" src="${escapeHtml(entry)}"></script>`,
+      );
+    }
+  }
+
+  return { head: headParts.join(""), tail: tailParts.join("") };
+}
+
+async function renderPage(context: RenderContext): Promise<string> {
+  const registry: IslandRegistry = { entries: new Map() };
+  const body = await buildBody(context, registry);
+  const bodyMarkup = await renderToStringAsync(body, context.signal);
+  const isIslandMode = context.route.mode === "island";
+  const { head, tail } = buildIslandHeadAndTail(
+    registry,
+    context.route.clientEntries,
+    isIslandMode,
+  );
+  return `<!DOCTYPE html><html><head>${head}</head><body>${bodyMarkup}${tail}</body></html>`;
+}
+
+function renderSpaShell(context: RenderContext): string {
+  const clientEntries = context.route.clientEntries;
+  const head: string[] = [];
+  const tail: string[] = [];
+  for (const entry of clientEntries) {
+    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>`;
+}
+
+export const reactRenderer: Renderer = {
+  name: "react",
+  async prerender(context) {
+    if (context.route.mode === "api") {
+      return serializeIslandProps(context.data);
+    }
+    if (context.route.mode === "spa") {
+      return renderSpaShell(context);
+    }
+    return renderPage(context);
+  },
+  async render(context) {
+    if (context.route.mode === "api") {
+      return new Response(serializeIslandProps(context.data), {
+        headers: { "content-type": "application/json; charset=utf-8" },
+      });
+    }
+    if (context.route.mode === "spa") {
+      return new Response(renderSpaShell(context), {
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
+    }
+    const html = await renderPage(context);
+    return new Response(html, {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  },
+};

package/src/serialize.ts

@@ -0,0 +1,37 @@
+const HTML_ESCAPE = /[<>&\u2028\u2029]/g;
+
+function escapeHtmlChar(char: string): string {
+  return `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}
+
+function escapeHtmlValue(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#x27;");
+}
+
+export function serializeIslandProps(value: unknown): string {
+  const seen = new WeakSet<object>();
+  function replacer(this: object, _key: string, v: unknown): unknown {
+    if (v === undefined) return undefined;
+    const type = typeof v;
+    if (type === "function" || type === "symbol" || type === "bigint") {
+      throw new TypeError(`cannot serialize ${type}`);
+    }
+    if (v !== null && (typeof v === "object" || Array.isArray(v))) {
+      if (seen.has(v)) throw new TypeError("cyclic reference");
+      seen.add(v);
+    }
+    return v;
+  }
+  const raw = JSON.stringify(value, replacer);
+  if (raw === undefined) return "null";
+  return raw.replace(HTML_ESCAPE, escapeHtmlChar);
+}
+
+export function escapeHtml(value: string): string {
+  return escapeHtmlValue(value);
+}