npm - @cloudwerk/ui - Versions diffs - 0.4.0 → 0.6.0 - Mend

@cloudwerk/ui 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { HydrationManifest } from '@cloudwerk/core';
 /**
  * @cloudwerk/ui - Type Definitions
  *
@@ -131,6 +133,135 @@ interface PropsWithChildren<_P = unknown> {
     children?: unknown;
 }
+/**
+ * @cloudwerk/ui - Hydration Utilities
+ *
+ * Server-side helpers for wrapping client components with hydration metadata
+ * and generating the client-side hydration bootstrap script.
+ */
+/**
+ * Options for wrapping a component for hydration.
+ */
+interface WrapForHydrationOptions {
+    /** Unique component ID */
+    componentId: string;
+    /** Props to serialize for client-side hydration */
+    props: Record<string, unknown>;
+    /** Custom wrapper element tag (default: 'div') */
+    wrapperTag?: string;
+}
+/**
+ * Options for generating hydration script.
+ */
+interface HydrationScriptOptions {
+    /** Whether to include source maps in development */
+    includeSourceMaps?: boolean;
+    /** Custom hydration endpoint path */
+    hydrationEndpoint?: string;
+}
+/**
+ * Wrap a server-rendered element with hydration metadata.
+ *
+ * This wraps the component's HTML output with a container element
+ * that includes data attributes for client-side hydration:
+ * - `data-hydrate-id`: The component ID for looking up the client bundle
+ * - `data-hydrate-props`: JSON-serialized props to pass during hydration
+ *
+ * @param html - Server-rendered HTML string
+ * @param options - Hydration options
+ * @returns HTML string with hydration wrapper
+ *
+ * @example
+ * ```typescript
+ * const html = wrapForHydration('<button>Count: 0</button>', {
+ *   componentId: 'components_Counter',
+ *   props: { initialCount: 0 },
+ * })
+ * // Returns:
+ * // <div data-hydrate-id="components_Counter" data-hydrate-props='{"initialCount":0}'>
+ * //   <button>Count: 0</button>
+ * // </div>
+ * ```
+ */
+declare function wrapForHydration(html: string, options: WrapForHydrationOptions): string;
+/**
+ * Generate the hydration bootstrap script to include in the HTML response.
+ *
+ * This script:
+ * 1. Finds all elements with `data-hydrate-id` attributes
+ * 2. Loads the corresponding client bundles
+ * 3. Hydrates each component with its serialized props
+ *
+ * @param manifest - Hydration manifest with component metadata
+ * @param options - Script generation options
+ * @returns Script tags for hydration
+ *
+ * @example
+ * ```typescript
+ * const script = generateHydrationScript(manifest, {
+ *   hydrationEndpoint: '/__cloudwerk',
+ * })
+ * // Insert at the end of the <body> tag
+ * ```
+ */
+declare function generateHydrationScript(manifest: HydrationManifest, options?: HydrationScriptOptions): string;
+/**
+ * Generate script tags for preloading client bundles.
+ *
+ * This adds modulepreload hints for better performance.
+ *
+ * @param manifest - Hydration manifest with component metadata
+ * @returns Link tags for modulepreload
+ */
+declare function generatePreloadHints(manifest: HydrationManifest): string;
+/**
+ * Generate the hydration runtime module for Hono JSX.
+ *
+ * This is served at `/__cloudwerk/runtime.js` and provides the render
+ * function that uses hono/jsx/dom for client-side hydration.
+ *
+ * The render function uses hono/jsx/dom's built-in virtual DOM diffing
+ * to safely update the DOM without raw HTML insertion.
+ *
+ * @returns JavaScript module source code
+ */
+declare function generateHydrationRuntime(): string;
+/**
+ * Generate the React hydration runtime module.
+ *
+ * This is served at `/__cloudwerk/react-runtime.js` and provides the
+ * hydrateRoot function from react-dom/client for client-side hydration.
+ *
+ * The runtime exports:
+ * - hydrateRoot from react-dom/client for hydration
+ * - React and all React hooks for client components
+ *
+ * @returns JavaScript module source code
+ */
+declare function generateReactHydrationRuntime(): string;
+/**
+ * Generate the React hydration bootstrap script to include in the HTML response.
+ *
+ * This script:
+ * 1. Finds all elements with `data-hydrate-id` attributes
+ * 2. Loads the corresponding client bundles
+ * 3. Hydrates each component with React's hydrateRoot
+ *
+ * @param manifest - Hydration manifest with component metadata
+ * @param options - Script generation options
+ * @returns Script tags for hydration
+ *
+ * @example
+ * ```typescript
+ * const script = generateReactHydrationScript(manifest, {
+ *   hydrationEndpoint: '/__cloudwerk',
+ * })
+ * // Insert at the end of the <body> tag
+ * ```
+ */
+declare function generateReactHydrationScript(manifest: HydrationManifest, options?: HydrationScriptOptions): string;
 /**
  * @cloudwerk/ui - Renderer Selection
  *
@@ -156,12 +287,32 @@ declare function getActiveRenderer(): Renderer;
  * console.log(`Using ${getActiveRendererName()} renderer`)
  */
 declare function getActiveRendererName(): string;
+/**
+ * Initialize and register the React renderer.
+ *
+ * This must be called before using setActiveRenderer('react').
+ * Requires react and react-dom packages to be installed.
+ *
+ * @throws Error if React packages are not installed
+ *
+ * @example
+ * import { initReactRenderer, setActiveRenderer } from '@cloudwerk/ui'
+ *
+ * // Initialize React renderer (requires react and react-dom)
+ * await initReactRenderer()
+ *
+ * // Now you can use React
+ * setActiveRenderer('react')
+ */
+declare function initReactRenderer(): Promise<void>;
 /**
  * Set the active renderer by name.
  *
  * Called during app initialization based on the `ui.renderer` config option.
  * The renderer must be registered (either built-in or via registerRenderer).
  *
+ * For the React renderer, you must call initReactRenderer() first.
+ *
  * @param name - Renderer name from config (e.g., 'hono-jsx', 'react')
  * @throws Error if renderer is not found
  *
@@ -197,7 +348,7 @@ declare function registerRenderer(name: string, renderer: Renderer): void;
  *
  * @example
  * const available = getAvailableRenderers()
- * // ['hono-jsx']
+ * // ['hono-jsx'] (or ['hono-jsx', 'react'] if initReactRenderer() was called)
  */
 declare function getAvailableRenderers(): string[];
 /**
@@ -379,4 +530,4 @@ declare function html(content: string, options?: HtmlOptions): Response;
  */
 declare function hydrate(element: unknown, root: Element): void;
-export { type HtmlOptions, type PropsWithChildren, type RenderOptions, type RenderToStreamOptions, type Renderer, type StreamRenderOptions, _resetRenderers, getActiveRenderer, getActiveRendererName, getAvailableRenderers, honoJsxRenderer, html, hydrate, registerRenderer, render, renderStream, renderToStream, setActiveRenderer };
+export { type HtmlOptions, type HydrationScriptOptions, type PropsWithChildren, type RenderOptions, type RenderToStreamOptions, type Renderer, type StreamRenderOptions, type WrapForHydrationOptions, _resetRenderers, generateHydrationRuntime, generateHydrationScript, generatePreloadHints, generateReactHydrationRuntime, generateReactHydrationScript, getActiveRenderer, getActiveRendererName, getAvailableRenderers, honoJsxRenderer, html, hydrate, initReactRenderer, registerRenderer, render, renderStream, renderToStream, setActiveRenderer, wrapForHydration };

package/dist/index.js CHANGED Viewed

@@ -46,17 +46,28 @@ var honoJsxRenderer = {
   /**
    * Hydrate a JSX element on the client.
    *
-   * This is a placeholder that throws an informative error.
-   * Client-side hydration will be implemented in issue #39.
+   * Uses hono/jsx/dom render function to attach event handlers and state
+   * to server-rendered HTML. This is called by the client-side hydration
+   * bootstrap script for each Client Component.
    *
-   * @param _element - JSX element (unused)
-   * @param _root - DOM element (unused)
-   * @throws Error with information about when this feature will be available
+   * Note: This method is primarily used by the client-side hydration runtime.
+   * In server-side code, it will throw an error since the DOM is not available.
+   *
+   * @param element - JSX element to hydrate
+   * @param root - DOM element to hydrate into
+   * @throws Error if called in a non-browser environment
    */
-  hydrate(_element, _root) {
-    throw new Error(
-      "Client hydration requires hono/jsx/dom. This feature will be available after issue #39 is implemented."
-    );
+  hydrate(element, root) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      throw new Error(
+        "hydrate() can only be called in a browser environment. For server-side rendering, use render() instead."
+      );
+    }
+    import("hono/jsx/dom").then(({ render: render2 }) => {
+      render2(element, root);
+    }).catch((error) => {
+      console.error("[Cloudwerk] Failed to hydrate component:", error);
+    });
   }
 };
 function renderStream(loadingElement, contentPromise, options = {}) {
@@ -144,10 +155,29 @@ function getActiveRenderer() {
 function getActiveRendererName() {
   return activeRendererName;
 }
+async function initReactRenderer() {
+  if (renderers["react"]) {
+    return;
+  }
+  try {
+    const { reactRenderer } = await import("./react-PVIKZSJC.js");
+    renderers["react"] = reactRenderer;
+  } catch (error) {
+    throw new Error(
+      `Failed to initialize React renderer. Make sure react and react-dom are installed: npm install react react-dom
+Original error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
 function setActiveRenderer(name) {
   const renderer = renderers[name];
   if (!renderer) {
     const available = Object.keys(renderers).join(", ");
+    if (name === "react") {
+      throw new Error(
+        `React renderer is not initialized. Call initReactRenderer() first, or install react and react-dom packages.`
+      );
+    }
     throw new Error(`Unknown renderer "${name}". Available renderers: ${available}`);
   }
   activeRenderer = renderer;
@@ -174,6 +204,266 @@ function _resetRenderers() {
   activeRendererName = "hono-jsx";
 }
+// src/hydration.ts
+import { serializeProps } from "@cloudwerk/core";
+function wrapForHydration(html2, options) {
+  const { componentId, props, wrapperTag = "div" } = options;
+  const serializedProps = serializeProps(props);
+  const escapedProps = escapeHtmlAttribute(serializedProps);
+  return `<${wrapperTag} data-hydrate-id="${componentId}" data-hydrate-props="${escapedProps}">${html2}</${wrapperTag}>`;
+}
+function escapeHtmlAttribute(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function generateHydrationScript(manifest, options = {}) {
+  const { hydrationEndpoint = "/__cloudwerk" } = options;
+  if (manifest.components.size === 0) {
+    return "";
+  }
+  const bundleMap = {};
+  for (const [id, meta] of manifest.components) {
+    bundleMap[id] = meta.bundlePath;
+  }
+  const script = `
+<script type="module">
+(async function() {
+  // Bundle map for component lookups
+  const bundles = ${JSON.stringify(bundleMap)};
+  // Find all elements that need hydration
+  const elements = document.querySelectorAll('[data-hydrate-id]');
+  if (elements.length === 0) return;
+  // Cache for loaded modules
+  const moduleCache = new Map();
+  // Load a component module
+  async function loadComponent(bundlePath) {
+    if (moduleCache.has(bundlePath)) {
+      return moduleCache.get(bundlePath);
+    }
+    const module = await import(bundlePath);
+    moduleCache.set(bundlePath, module);
+    return module;
+  }
+  // Hydrate each element
+  for (const el of elements) {
+    const componentId = el.getAttribute('data-hydrate-id');
+    const propsJson = el.getAttribute('data-hydrate-props');
+    if (!componentId || !bundles[componentId]) {
+      console.warn('[Cloudwerk] Unknown client component:', componentId);
+      continue;
+    }
+    try {
+      // Parse props
+      const props = propsJson ? JSON.parse(propsJson) : {};
+      // Load the component module
+      const bundlePath = bundles[componentId];
+      const module = await loadComponent(bundlePath);
+      const Component = module.default;
+      if (!Component) {
+        console.error('[Cloudwerk] No default export in component:', componentId);
+        continue;
+      }
+      // Import hono/jsx/dom for hydration
+      const { render } = await import('${hydrationEndpoint}/runtime.js');
+      // Hydrate the component using hono/jsx/dom render
+      // This safely replaces content using virtual DOM diffing
+      render(Component(props), el);
+      // Remove hydration attributes after successful hydration
+      el.removeAttribute('data-hydrate-id');
+      el.removeAttribute('data-hydrate-props');
+    } catch (error) {
+      console.error('[Cloudwerk] Failed to hydrate component:', componentId, error);
+    }
+  }
+})();
+</script>
+`.trim();
+  return script;
+}
+function generatePreloadHints(manifest) {
+  if (manifest.components.size === 0) {
+    return "";
+  }
+  const hints = [];
+  for (const meta of manifest.components.values()) {
+    hints.push(`<link rel="modulepreload" href="${meta.bundlePath}">`);
+  }
+  return hints.join("\n");
+}
+function generateHydrationRuntime() {
+  return `
+// Cloudwerk Hydration Runtime
+// Uses hono/jsx/dom for client-side rendering with virtual DOM diffing
+import { render as honoRender } from 'hono/jsx/dom';
+export function render(element, container) {
+  // Use hono/jsx/dom render which safely updates DOM via virtual DOM diffing
+  // This replaces the server-rendered content with the interactive version
+  honoRender(element, container);
+}
+// Re-export hooks for client components
+export {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  useMemo,
+  useReducer,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useId,
+} from 'hono/jsx/dom';
+`.trim();
+}
+function generateReactHydrationRuntime() {
+  return `
+// Cloudwerk React Hydration Runtime
+// Uses react-dom/client for client-side hydration
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  useMemo,
+  useReducer,
+  useContext,
+  useLayoutEffect,
+  useImperativeHandle,
+  useDebugValue,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useId,
+  useInsertionEffect,
+  useOptimistic,
+  useActionState,
+  use,
+} from 'react';
+// Re-export React for component rendering
+export { React };
+// Re-export hydrateRoot for hydration
+export { hydrateRoot };
+// Hydrate function that wraps hydrateRoot for Cloudwerk usage
+export function hydrate(Component, props, container) {
+  return hydrateRoot(container, React.createElement(Component, props));
+}
+// Re-export all hooks for client components
+export {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  useMemo,
+  useReducer,
+  useContext,
+  useLayoutEffect,
+  useImperativeHandle,
+  useDebugValue,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useId,
+  useInsertionEffect,
+  useOptimistic,
+  useActionState,
+  use,
+};
+`.trim();
+}
+function generateReactHydrationScript(manifest, options = {}) {
+  const { hydrationEndpoint = "/__cloudwerk" } = options;
+  if (manifest.components.size === 0) {
+    return "";
+  }
+  const bundleMap = {};
+  for (const [id, meta] of manifest.components) {
+    bundleMap[id] = meta.bundlePath;
+  }
+  const script = `
+<script type="module">
+(async function() {
+  // Bundle map for component lookups
+  const bundles = ${JSON.stringify(bundleMap)};
+  // Find all elements that need hydration
+  const elements = document.querySelectorAll('[data-hydrate-id]');
+  if (elements.length === 0) return;
+  // Cache for loaded modules
+  const moduleCache = new Map();
+  // Load a component module
+  async function loadComponent(bundlePath) {
+    if (moduleCache.has(bundlePath)) {
+      return moduleCache.get(bundlePath);
+    }
+    const module = await import(bundlePath);
+    moduleCache.set(bundlePath, module);
+    return module;
+  }
+  // Import React and hydrateRoot from the runtime
+  const { React, hydrateRoot } = await import('${hydrationEndpoint}/react-runtime.js');
+  // Hydrate each element
+  for (const el of elements) {
+    const componentId = el.getAttribute('data-hydrate-id');
+    const propsJson = el.getAttribute('data-hydrate-props');
+    if (!componentId || !bundles[componentId]) {
+      console.warn('[Cloudwerk] Unknown client component:', componentId);
+      continue;
+    }
+    try {
+      // Parse props
+      const props = propsJson ? JSON.parse(propsJson) : {};
+      // Load the component module
+      const bundlePath = bundles[componentId];
+      const module = await loadComponent(bundlePath);
+      const Component = module.default;
+      if (!Component) {
+        console.error('[Cloudwerk] No default export in component:', componentId);
+        continue;
+      }
+      // Hydrate the component using React's hydrateRoot
+      // This attaches event handlers to the server-rendered HTML
+      hydrateRoot(el, React.createElement(Component, props));
+      // Remove hydration attributes after successful hydration
+      el.removeAttribute('data-hydrate-id');
+      el.removeAttribute('data-hydrate-props');
+    } catch (error) {
+      console.error('[Cloudwerk] Failed to hydrate component:', componentId, error);
+    }
+  }
+})();
+</script>
+`.trim();
+  return script;
+}
 // src/index.ts
 function render(element, options) {
   return getActiveRenderer().render(element, options);
@@ -186,15 +476,22 @@ function hydrate(element, root) {
 }
 export {
   _resetRenderers,
+  generateHydrationRuntime,
+  generateHydrationScript,
+  generatePreloadHints,
+  generateReactHydrationRuntime,
+  generateReactHydrationScript,
   getActiveRenderer,
   getActiveRendererName,
   getAvailableRenderers,
   honoJsxRenderer,
   html,
   hydrate,
+  initReactRenderer,
   registerRenderer,
   render,
   renderStream,
   renderToStream,
-  setActiveRenderer
+  setActiveRenderer,
+  wrapForHydration
 };

package/dist/react-PVIKZSJC.js ADDED Viewed

@@ -0,0 +1,104 @@
+// src/renderers/react.ts
+import { renderToString, renderToReadableStream } from "react-dom/server";
+var reactRenderer = {
+  /**
+   * Render a React element to an HTML Response.
+   *
+   * Uses React's renderToString() for synchronous server-side rendering.
+   * This method wraps the output in a proper Response object with headers.
+   *
+   * @param element - React element (React.ReactElement)
+   * @param options - Render options
+   * @returns Response object with HTML content
+   */
+  render(element, options = {}) {
+    const { status = 200, headers = {}, doctype = true } = options;
+    const htmlString = renderToString(element);
+    const body = doctype ? `<!DOCTYPE html>${htmlString}` : htmlString;
+    return new Response(body, {
+      status,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        ...headers
+      }
+    });
+  },
+  /**
+   * Create an HTML Response from a raw string.
+   *
+   * Useful for static HTML, templates, or pre-rendered content
+   * that doesn't need to go through JSX rendering.
+   *
+   * @param content - Raw HTML string
+   * @param options - HTML response options
+   * @returns Response object with HTML content
+   */
+  html(content, options = {}) {
+    const { status = 200, headers = {} } = options;
+    return new Response(content, {
+      status,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        ...headers
+      }
+    });
+  },
+  /**
+   * Hydrate a React element on the client.
+   *
+   * Uses react-dom/client's hydrateRoot to attach event handlers and state
+   * to server-rendered HTML. This is called by the client-side hydration
+   * runtime for each Client Component.
+   *
+   * Note: This method is primarily used by the client-side hydration runtime.
+   * In server-side code, it will throw an error since the DOM is not available.
+   *
+   * @param element - React element to hydrate
+   * @param root - DOM element to hydrate into
+   * @throws Error if called in a non-browser environment
+   */
+  hydrate(element, root) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      throw new Error(
+        "hydrate() can only be called in a browser environment. For server-side rendering, use render() instead."
+      );
+    }
+    import("react-dom/client").then(({ hydrateRoot }) => {
+      hydrateRoot(root, element);
+    }).catch((error) => {
+      console.error("[Cloudwerk] Failed to hydrate React component:", error);
+    });
+  }
+};
+function prependDoctype(stream) {
+  const encoder = new TextEncoder();
+  const doctypeBytes = encoder.encode("<!DOCTYPE html>");
+  let doctypeSent = false;
+  return stream.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        if (!doctypeSent) {
+          controller.enqueue(doctypeBytes);
+          doctypeSent = true;
+        }
+        controller.enqueue(chunk);
+      }
+    })
+  );
+}
+async function reactRenderToStream(element, options = {}) {
+  const { status = 200, headers = {}, doctype = true } = options;
+  const contentStream = await renderToReadableStream(element);
+  const stream = doctype ? prependDoctype(contentStream) : contentStream;
+  return new Response(stream, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      ...headers
+    }
+  });
+}
+export {
+  reactRenderToStream,
+  reactRenderer
+};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cloudwerk/ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "UI rendering abstraction for Cloudwerk",
   "repository": {
     "type": "git",
@@ -17,20 +17,36 @@
   "files": [
     "dist"
   ],
-  "dependencies": {},
+  "dependencies": {
+    "@cloudwerk/core": "0.6.0"
+  },
   "peerDependencies": {
-    "hono": "^4.0.0"
+    "hono": "^4.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@vitest/coverage-v8": "^1.0.0",
     "hono": "^4.7.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "test": "vitest --run",
     "test:watch": "vitest",
     "test:coverage": "vitest --run --coverage",