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

@cloudwerk/ui 0.1.1 → 0.4.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 (3) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -74,6 +74,44 @@ interface HtmlOptions {
      */
     headers?: Record<string, string>;
 }
+/**
+ * Options for streaming render (loading-swap pattern).
+ */
+interface StreamRenderOptions {
+    /**
+     * HTTP status code for the response.
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     * These are merged with the default Content-Type and Transfer-Encoding headers.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for native progressive streaming render with Suspense boundaries.
+ *
+ * This is used by renderToStream() which uses Hono's renderToReadableStream
+ * for native progressive streaming with Suspense support.
+ */
+interface RenderToStreamOptions {
+    /**
+     * HTTP status code for the response.
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     * These are merged with the default Content-Type header.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to include the <!DOCTYPE html> declaration.
+     * @default true
+     */
+    doctype?: boolean;
+}
 /**
  * Props for components that receive children.
  *
@@ -187,9 +225,77 @@ declare function _resetRenderers(): void;
  * - Automatic doctype handling
  * - Proper Content-Type headers
  *
- * Note: Streaming support via renderToReadableStream will be added in issue #38.
+ * Native progressive streaming is available via renderToStream() using Hono's
+ * renderToReadableStream for Suspense boundary support.
  */
 declare const honoJsxRenderer: Renderer;
+/**
+ * Create a streaming HTML Response that sends loading UI immediately,
+ * then streams the final content when the content promise resolves.
+ *
+ * This uses a chunked transfer encoding to send HTML in two parts:
+ * 1. Loading UI (sent immediately)
+ * 2. Final content with script to replace loading UI (sent when ready)
+ *
+ * Note: The innerHTML assignment in the client script is safe because we only
+ * use server-rendered content that we control. No user input is directly
+ * inserted into the HTML.
+ *
+ * @param loadingElement - Loading UI to show immediately (JSX element)
+ * @param contentPromise - Promise that resolves to final content (JSX element)
+ * @param options - Streaming render options
+ * @returns Response object with streaming HTML content
+ *
+ * @example
+ * const loadingElement = <Loading params={{}} searchParams={{}} pathname="/dashboard" />
+ * const contentPromise = (async () => {
+ *   const data = await loader()
+ *   return <Page {...data} />
+ * })()
+ *
+ * return renderStream(loadingElement, contentPromise)
+ */
+declare function renderStream(loadingElement: unknown, contentPromise: Promise<unknown>, options?: StreamRenderOptions): Response;
+/**
+ * Render a JSX element to a streaming Response using native progressive streaming.
+ *
+ * This uses Hono's renderToReadableStream for native support of React-style
+ * Suspense boundaries. Content inside Suspense components will be progressively
+ * streamed as their async content resolves.
+ *
+ * Unlike renderStream() which uses a loading-swap pattern, this function
+ * provides true progressive streaming where:
+ * - The initial shell is sent immediately
+ * - Suspense fallbacks are shown while async content loads
+ * - Async content is streamed in-place as it resolves
+ * - No JavaScript is required for the initial render
+ *
+ * @param element - Hono JSX element to render (may contain Suspense boundaries)
+ * @param options - Render options
+ * @returns Promise resolving to Response with streaming HTML content
+ *
+ * @example
+ * // In a route handler
+ * import { Suspense } from 'hono/jsx/streaming'
+ *
+ * function Page() {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <h1>Dashboard</h1>
+ *         <Suspense fallback={<p>Loading stats...</p>}>
+ *           <AsyncStats />
+ *         </Suspense>
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ *
+ * export function GET() {
+ *   return renderToStream(<Page />)
+ * }
+ */
+declare function renderToStream(element: unknown, options?: RenderToStreamOptions): Promise<Response>;
 /**
  * @cloudwerk/ui
@@ -273,4 +379,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 Renderer, _resetRenderers, getActiveRenderer, getActiveRendererName, getAvailableRenderers, honoJsxRenderer, html, hydrate, registerRenderer, render, setActiveRenderer };
+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 };

package/dist/index.js CHANGED Viewed

@@ -1,4 +1,5 @@
 // src/renderers/hono-jsx.ts
+import { renderToReadableStream } from "hono/jsx/streaming";
 var honoJsxRenderer = {
   /**
    * Render a JSX element to an HTML Response.
@@ -58,6 +59,78 @@ var honoJsxRenderer = {
     );
   }
 };
+function renderStream(loadingElement, contentPromise, options = {}) {
+  const { status = 200, headers = {} } = options;
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      try {
+        const loadingHtml = String(loadingElement);
+        const loadingWrapper = `<!DOCTYPE html><div id="__cloudwerk_loading">${loadingHtml}</div>`;
+        controller.enqueue(encoder.encode(loadingWrapper));
+        const finalElement = await contentPromise;
+        const finalHtml = String(finalElement);
+        const replacementScript = `
+<script>
+(function() {
+  var loading = document.getElementById('__cloudwerk_loading');
+  if (loading) {
+    var content = document.getElementById('__cloudwerk_content');
+    if (content) {
+      document.body.innerHTML = content.innerHTML;
+    }
+  }
+})();
+</script>
+<div id="__cloudwerk_content" style="display:none">${finalHtml}</div>
+`;
+        controller.enqueue(encoder.encode(replacementScript));
+        controller.close();
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorHtml = `<div style="color:red;padding:20px;">Error loading content: ${errorMessage}</div>`;
+        controller.enqueue(encoder.encode(errorHtml));
+        controller.close();
+      }
+    }
+  });
+  return new Response(stream, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Transfer-Encoding": "chunked",
+      ...headers
+    }
+  });
+}
+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 renderToStream(element, options = {}) {
+  const { status = 200, headers = {}, doctype = true } = options;
+  const contentStream = renderToReadableStream(element);
+  const stream = doctype ? prependDoctype(contentStream) : contentStream;
+  return new Response(stream, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      ...headers
+    }
+  });
+}
 // src/renderer.ts
 var renderers = {
@@ -121,5 +194,7 @@ export {
   hydrate,
   registerRenderer,
   render,
+  renderStream,
+  renderToStream,
   setActiveRenderer
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cloudwerk/ui",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "UI rendering abstraction for Cloudwerk",
   "repository": {
     "type": "git",