npm - @alepha/react - Versions diffs - 0.15.0 → 0.15.1 - Mend

@alepha/react 0.15.0 → 0.15.1

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 (81) hide show

package/dist/auth/index.browser.js +603 -242
package/dist/auth/index.browser.js.map +1 -1
package/dist/auth/index.d.ts +6 -6
package/dist/auth/index.d.ts.map +1 -1
package/dist/auth/index.js +1296 -922
package/dist/auth/index.js.map +1 -1
package/dist/core/index.d.ts +128 -128
package/dist/core/index.d.ts.map +1 -1
package/dist/core/index.js +20 -20
package/dist/core/index.js.map +1 -1
package/dist/form/index.d.ts +36 -36
package/dist/form/index.d.ts.map +1 -1
package/dist/form/index.js +15 -15
package/dist/form/index.js.map +1 -1
package/dist/head/index.browser.js +20 -0
package/dist/head/index.browser.js.map +1 -1
package/dist/head/index.d.ts +73 -65
package/dist/head/index.d.ts.map +1 -1
package/dist/head/index.js +20 -0
package/dist/head/index.js.map +1 -1
package/dist/i18n/index.d.ts +37 -37
package/dist/i18n/index.d.ts.map +1 -1
package/dist/i18n/index.js.map +1 -1
package/dist/router/index.browser.js +605 -244
package/dist/router/index.browser.js.map +1 -1
package/dist/router/index.d.ts +539 -550
package/dist/router/index.d.ts.map +1 -1
package/dist/router/index.js +1296 -922
package/dist/router/index.js.map +1 -1
package/dist/websocket/index.d.ts +38 -38
package/dist/websocket/index.d.ts.map +1 -1
package/package.json +6 -6
package/src/auth/__tests__/$auth.spec.ts +162 -147
package/src/auth/index.ts +9 -3
package/src/auth/services/ReactAuth.ts +15 -5
package/src/core/hooks/useAction.ts +1 -2
package/src/core/index.ts +4 -4
package/src/form/errors/FormValidationError.ts +4 -6
package/src/form/hooks/useFormState.ts +1 -1
package/src/form/index.ts +1 -1
package/src/form/services/FormModel.ts +31 -25
package/src/head/helpers/SeoExpander.ts +2 -1
package/src/head/hooks/useHead.spec.tsx +2 -2
package/src/head/index.browser.ts +2 -2
package/src/head/index.ts +4 -4
package/src/head/interfaces/Head.ts +15 -3
package/src/head/primitives/$head.ts +2 -5
package/src/head/providers/BrowserHeadProvider.ts +55 -0
package/src/head/providers/HeadProvider.ts +4 -1
package/src/i18n/__tests__/integration.spec.tsx +1 -1
package/src/i18n/components/Localize.spec.tsx +2 -2
package/src/i18n/hooks/useI18n.browser.spec.tsx +2 -2
package/src/i18n/index.ts +1 -1
package/src/i18n/primitives/$dictionary.ts +1 -1
package/src/i18n/providers/I18nProvider.spec.ts +1 -1
package/src/i18n/providers/I18nProvider.ts +1 -1
package/src/router/__tests__/page-head-browser.browser.spec.ts +5 -1
package/src/router/__tests__/page-head.spec.ts +11 -7
package/src/router/__tests__/seo-head.spec.ts +7 -3
package/src/router/atoms/ssrManifestAtom.ts +2 -11
package/src/router/components/ErrorViewer.tsx +626 -167
package/src/router/components/Link.tsx +4 -2
package/src/router/components/NestedView.tsx +7 -9
package/src/router/components/NotFound.tsx +2 -2
package/src/router/hooks/useQueryParams.ts +1 -1
package/src/router/hooks/useRouter.ts +1 -1
package/src/router/hooks/useRouterState.ts +1 -1
package/src/router/index.browser.ts +10 -11
package/src/router/index.shared.ts +7 -7
package/src/router/index.ts +10 -7
package/src/router/primitives/$page.browser.spec.tsx +6 -1
package/src/router/primitives/$page.spec.tsx +7 -1
package/src/router/primitives/$page.ts +5 -9
package/src/router/providers/ReactBrowserProvider.ts +17 -6
package/src/router/providers/ReactBrowserRouterProvider.ts +1 -1
package/src/router/providers/ReactPageProvider.ts +4 -3
package/src/router/providers/ReactServerProvider.ts +29 -37
package/src/router/providers/ReactServerTemplateProvider.ts +300 -137
package/src/router/providers/SSRManifestProvider.ts +17 -60
package/src/router/services/ReactPageService.ts +4 -1
package/src/router/services/ReactRouter.ts +6 -5

package/src/router/providers/ReactServerTemplateProvider.ts CHANGED Viewed

@@ -1,6 +1,11 @@
+import { AlephaContext } from "@alepha/react";
+import type { SimpleHead } from "@alepha/react/head";
 import { $inject, Alepha, AlephaError } from "alepha";
 import { $logger } from "alepha/logger";
-import type { SimpleHead } from "@alepha/react/head";
+import { createElement, type ReactNode } from "react";
+import { renderToString } from "react-dom/server";
+import ErrorViewer from "../components/ErrorViewer.tsx";
+import { Redirection } from "../errors/Redirection.ts";
 import type { ReactRouterState } from "./ReactPageProvider.ts";
 /**
@@ -39,7 +44,6 @@ export class ReactServerTemplateProvider {
    */
   protected slots: TemplateSlots | null = null;
   /**
    * Root element ID for React mounting.
    */
@@ -93,8 +97,6 @@ export class ReactServerTemplateProvider {
    *
    * This should be called once during server startup/configuration.
    * The parsed slots are cached and reused for all requests.
-   *
-   * @param template - The HTML template string (typically index.html)
    */
   public parseTemplate(template: string): TemplateSlots {
     this.log.debug("Parsing template into slots");
@@ -168,7 +170,7 @@ export class ReactServerTemplateProvider {
     this.slots = {
       // Pre-encoded static parts
-      doctype: this.encoder.encode(doctype + "\n"),
+      doctype: this.encoder.encode(`${doctype}\n`),
       htmlOpen: this.encoder.encode("<html"),
       htmlClose: this.encoder.encode(">\n"),
       headOpen: this.encoder.encode("<head>"),
@@ -209,9 +211,8 @@ export class ReactServerTemplateProvider {
     // Match: key="value", key='value', key=value, or just key (boolean)
     const attrRegex = /([^\s=]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
-    let match: RegExpExecArray | null;
-    while ((match = attrRegex.exec(attrStr))) {
+    for (const match of attrStr.matchAll(attrRegex)) {
       const key = match[1];
       const value = match[2] ?? match[3] ?? match[4] ?? "";
       attrs[key] = value;
@@ -331,10 +332,14 @@ export class ReactServerTemplateProvider {
   protected renderLinkTag(link: {
     rel: string;
     href: string;
+    type?: string;
     as?: string;
     crossorigin?: string;
   }): string {
     let tag = `<link rel="${this.escapeHtml(link.rel)}" href="${this.escapeHtml(link.href)}"`;
+    if (link.type) {
+      tag += ` type="${this.escapeHtml(link.type)}"`;
+    }
     if (link.as) {
       tag += ` as="${this.escapeHtml(link.as)}"`;
     }
@@ -348,14 +353,30 @@ export class ReactServerTemplateProvider {
   /**
    * Render a script tag.
    */
-  protected renderScriptTag(script: Record<string, string | boolean>): string {
-    const attrs = Object.entries(script)
-      .filter(([, value]) => value !== false)
+  protected renderScriptTag(
+    script:
+      | string
+      | (Record<string, string | boolean | undefined> & { content?: string }),
+  ): string {
+    // Handle plain string as inline script
+    if (typeof script === "string") {
+      return `<script>${script}</script>\n`;
+    }
+    const { content, ...rest } = script;
+    const attrs = Object.entries(rest)
+      .filter(([, value]) => value !== false && value !== undefined)
       .map(([key, value]) => {
         if (value === true) return key;
         return `${key}="${this.escapeHtml(String(value))}"`;
       })
       .join(" ");
+    if (content) {
+      return attrs
+        ? `<script ${attrs}>${content}</script>\n`
+        : `<script>${content}</script>\n`;
+    }
     return `<script ${attrs}></script>\n`;
   }
@@ -393,25 +414,30 @@ export class ReactServerTemplateProvider {
       this.alepha.context.als?.getStore() ?? {};
     const layers = state.layers.map((layer) => ({
-      name: layer.name,
-      props: layer.props,
-      config: layer.config,
+      part: layer.part, // mandatory for previous-checking
+      name: layer.name, // mandatory for previous-checking
+      config: layer.config, // mandatory for previous-checking (contains 'query' & 'params')
+      props: layer.props, // our not-so-secret data cache
       error: layer.error
         ? {
-          ...layer.error,
-          name: layer.error.name,
-          message: layer.error.message,
-          stack: !this.alepha.isProduction() ? layer.error.stack : undefined,
-        }
+            ...layer.error,
+            name: layer.error.name,
+            message: layer.error.message,
+            stack: !this.alepha.isProduction() ? layer.error.stack : undefined,
+          }
         : undefined,
     }));
     const hydrationData: HydrationData = {
       layers,
-    }
+    };
     for (const [key, value] of Object.entries(store)) {
-      if (key.charAt(0) !== "_" && key !== "alepha.react.router.state" && key !== "registry") {
+      if (
+        key.charAt(0) !== "_" &&
+        key !== "alepha.react.router.state" &&
+        key !== "registry"
+      ) {
         hydrationData[key] = value;
       }
     }
@@ -420,24 +446,82 @@ export class ReactServerTemplateProvider {
   }
   /**
-   * Encode a string to Uint8Array using the shared encoder.
+   * Stream the body content: body tag, root div, React content, hydration, and closing tags.
+   *
+   * If an error occurs during React streaming, it injects error HTML instead of aborting,
+   * ensuring users see an error message rather than a white screen.
    */
-  public encode(str: string): Uint8Array {
-    return this.encoder.encode(str);
-  }
+  protected async streamBodyContent(
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    reactStream: ReadableStream<Uint8Array>,
+    state: ReactRouterState,
+    hydration: boolean,
+  ): Promise<void> {
+    const slots = this.getSlots();
+    const encoder = this.encoder;
+    const head = state.head;
-  /**
-   * Get the pre-encoded hydration script prefix.
-   */
-  public get hydrationPrefix(): Uint8Array {
-    return this.ENCODED.HYDRATION_PREFIX;
-  }
+    // <body ...>
+    controller.enqueue(slots.bodyOpen);
+    controller.enqueue(
+      encoder.encode(this.renderMergedBodyAttrs(head?.bodyAttributes)),
+    );
+    controller.enqueue(slots.bodyClose);
-  /**
-   * Get the pre-encoded hydration script suffix.
-   */
-  public get hydrationSuffix(): Uint8Array {
-    return this.ENCODED.HYDRATION_SUFFIX;
+    // Content before root (if any)
+    if (slots.beforeRoot) {
+      controller.enqueue(encoder.encode(slots.beforeRoot));
+    }
+    // <div id="root">
+    controller.enqueue(slots.rootOpen);
+    // Stream React content - catch errors from the React stream
+    const reader = reactStream.getReader();
+    let streamError: unknown = null;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        controller.enqueue(value);
+      }
+    } catch (error) {
+      // React stream errored - save for error HTML injection
+      streamError = error;
+      this.log.error("Error during React stream reading", error);
+    } finally {
+      reader.releaseLock();
+    }
+    // If React stream errored, inject error HTML inside the root div
+    if (streamError) {
+      this.injectErrorHtml(controller, encoder, slots, streamError, state, {
+        headClosed: true,
+        bodyStarted: true,
+      });
+      // injectErrorHtml already closes the document, so return early
+      return;
+    }
+    // </div>
+    controller.enqueue(slots.rootClose);
+    // Content after root (if any)
+    if (slots.afterRoot) {
+      controller.enqueue(encoder.encode(slots.afterRoot));
+    }
+    // Hydration script
+    if (hydration) {
+      const hydrationData = this.buildHydrationData(state);
+      controller.enqueue(this.ENCODED.HYDRATION_PREFIX);
+      controller.enqueue(encoder.encode(this.safeJsonSerialize(hydrationData)));
+      controller.enqueue(this.ENCODED.HYDRATION_SUFFIX);
+    }
+    // </body></html>
+    controller.enqueue(slots.scriptClose);
   }
   /**
@@ -468,72 +552,31 @@ export class ReactServerTemplateProvider {
     return new ReadableStream<Uint8Array>({
       start: async (controller) => {
         try {
-          // 1. DOCTYPE
+          // DOCTYPE
           controller.enqueue(slots.doctype);
-          // 2. <html ...>
+          // <html ...>
           controller.enqueue(slots.htmlOpen);
           controller.enqueue(
             encoder.encode(this.renderMergedHtmlAttrs(head?.htmlAttributes)),
           );
           controller.enqueue(slots.htmlClose);
-          // 3. <head>...</head>
+          // <head>...</head>
           controller.enqueue(slots.headOpen);
-          // Include early head content (entry.js, CSS) if set
           if (this.earlyHeadContent) {
             controller.enqueue(encoder.encode(this.earlyHeadContent));
           }
           controller.enqueue(encoder.encode(this.renderHeadContent(head)));
           controller.enqueue(slots.headClose);
-          // 4. <body ...>
-          controller.enqueue(slots.bodyOpen);
-          controller.enqueue(
-            encoder.encode(this.renderMergedBodyAttrs(head?.bodyAttributes)),
+          // Body content (body, root, React, hydration, closing tags)
+          await this.streamBodyContent(
+            controller,
+            reactStream,
+            state,
+            hydration,
           );
-          controller.enqueue(slots.bodyClose);
-          // 5. Content before root (if any)
-          if (slots.beforeRoot) {
-            controller.enqueue(encoder.encode(slots.beforeRoot));
-          }
-          // 6. <div id="root">
-          controller.enqueue(slots.rootOpen);
-          // 7. Stream React content
-          const reader = reactStream.getReader();
-          try {
-            while (true) {
-              const { done, value } = await reader.read();
-              if (done) break;
-              controller.enqueue(value);
-            }
-          } finally {
-            reader.releaseLock();
-          }
-          // 8. </div>
-          controller.enqueue(slots.rootClose);
-          // 9. Content after root (if any)
-          if (slots.afterRoot) {
-            controller.enqueue(encoder.encode(slots.afterRoot));
-          }
-          // 10. Hydration script
-          if (hydration) {
-            const hydrationData = this.buildHydrationData(state);
-            controller.enqueue(this.ENCODED.HYDRATION_PREFIX);
-            controller.enqueue(
-              encoder.encode(this.safeJsonSerialize(hydrationData)),
-            );
-            controller.enqueue(this.ENCODED.HYDRATION_SUFFIX);
-          }
-          // 11. </body></html>
-          controller.enqueue(slots.scriptClose);
           controller.close();
         } catch (error) {
@@ -635,15 +678,20 @@ export class ReactServerTemplateProvider {
     const slots = this.getSlots();
     const encoder = this.encoder;
+    // Track streaming state for error recovery
+    let headClosed = false;
+    let bodyStarted = false;
+    let routerState: ReactRouterState | undefined;
     return new ReadableStream<Uint8Array>({
       start: async (controller) => {
         try {
           // === EARLY PHASE (before async work) ===
-          // 1. DOCTYPE
+          // DOCTYPE
           controller.enqueue(slots.doctype);
-          // 2. <html ...> with global htmlAttributes only
+          // <html ...> with global htmlAttributes only
           controller.enqueue(slots.htmlOpen);
           controller.enqueue(
             encoder.encode(
@@ -652,7 +700,7 @@ export class ReactServerTemplateProvider {
           );
           controller.enqueue(slots.htmlClose);
-          // 3. <head> open + entry preloads
+          // <head> open + entry preloads
           controller.enqueue(slots.headOpen);
           if (this.earlyHeadContent) {
             controller.enqueue(encoder.encode(this.earlyHeadContent));
@@ -681,73 +729,188 @@ export class ReactServerTemplateProvider {
           }
           const { state, reactStream } = result;
-          const head = state.head;
+          routerState = state;
           // === LATE PHASE (after async work) ===
-          // 4. Rest of head content (title, meta, links from loaders)
-          controller.enqueue(encoder.encode(this.renderHeadContent(head)));
-          controller.enqueue(slots.headClose);
-          // 5. <body ...> with merged bodyAttributes
-          controller.enqueue(slots.bodyOpen);
+          // Rest of head content (title, meta, links from loaders)
           controller.enqueue(
-            encoder.encode(this.renderMergedBodyAttrs(head?.bodyAttributes)),
+            encoder.encode(this.renderHeadContent(state.head)),
+          );
+          controller.enqueue(slots.headClose);
+          headClosed = true;
+          // Body content (body, root, React, hydration, closing tags)
+          bodyStarted = true;
+          await this.streamBodyContent(
+            controller,
+            reactStream,
+            state,
+            hydration,
           );
-          controller.enqueue(slots.bodyClose);
-          // 6. Content before root (if any)
-          if (slots.beforeRoot) {
-            controller.enqueue(encoder.encode(slots.beforeRoot));
-          }
-          // 7. <div id="root">
-          controller.enqueue(slots.rootOpen);
+          controller.close();
+        } catch (error) {
+          onError?.(error);
-          // 8. Stream React content
-          const reader = reactStream.getReader();
+          // Instead of aborting the stream, inject error HTML so user sees
+          // an error message instead of white screen.
+          // React 19 streaming SSR doesn't reliably trigger ErrorBoundary,
+          // so we must handle it at the stream level.
           try {
-            while (true) {
-              const { done, value } = await reader.read();
-              if (done) break;
-              controller.enqueue(value);
-            }
-          } finally {
-            reader.releaseLock();
+            this.injectErrorHtml(
+              controller,
+              encoder,
+              slots,
+              error,
+              routerState,
+              { headClosed, bodyStarted },
+            );
+            controller.close();
+          } catch {
+            // If error injection fails, abort as last resort
+            controller.error(error);
           }
+        }
+      },
+    });
+  }
-          // 9. </div>
-          controller.enqueue(slots.rootClose);
+  /**
+   * Inject error HTML into the stream when an error occurs during streaming.
+   *
+   * Uses the router state's onError handler to render the error component,
+   * falling back to ErrorViewer if no custom handler is defined.
+   * Renders using renderToString to produce static HTML.
+   *
+   * Since we may have already sent partial HTML (DOCTYPE, <html>, <head>),
+   * we need to complete the document with an error message instead of aborting.
+   *
+   * Handles different states:
+   * - headClosed=false, bodyStarted=false: Need to add head content, close head, open body, add error, close all
+   * - headClosed=true, bodyStarted=false: Need to open body, add error, close all
+   * - headClosed=true, bodyStarted=true: Already inside root div, add error, close all
+   */
+  protected injectErrorHtml(
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    encoder: TextEncoder,
+    slots: TemplateSlots,
+    error: unknown,
+    routerState: ReactRouterState | undefined,
+    streamState: { headClosed: boolean; bodyStarted: boolean },
+  ): void {
+    // If head not closed, add remaining head content first
+    if (!streamState.headClosed) {
+      // Include original head content (CSS, scripts) and any head from router state
+      const headContent = this.renderHeadContent(routerState?.head);
+      if (headContent) {
+        controller.enqueue(encoder.encode(headContent));
+      }
+      controller.enqueue(slots.headClose);
+    }
-          // 10. Content after root (if any)
-          if (slots.afterRoot) {
-            controller.enqueue(encoder.encode(slots.afterRoot));
-          }
+    // If body hasn't started, we need to open body and root div
+    if (!streamState.bodyStarted) {
+      // Open body with any body attributes from state
+      controller.enqueue(slots.bodyOpen);
+      controller.enqueue(
+        encoder.encode(
+          this.renderMergedBodyAttrs(routerState?.head?.bodyAttributes),
+        ),
+      );
+      controller.enqueue(slots.bodyClose);
-          // 11. Hydration script
-          if (hydration) {
-            const hydrationData = this.buildHydrationData(state);
-            controller.enqueue(this.ENCODED.HYDRATION_PREFIX);
-            controller.enqueue(
-              encoder.encode(this.safeJsonSerialize(hydrationData)),
-            );
-            controller.enqueue(this.ENCODED.HYDRATION_SUFFIX);
-          }
+      // Content before root (if any)
+      if (slots.beforeRoot) {
+        controller.enqueue(encoder.encode(slots.beforeRoot));
+      }
-          // 12. </body></html>
-          controller.enqueue(slots.scriptClose);
+      controller.enqueue(slots.rootOpen);
+    }
-          controller.close();
-        } catch (error) {
-          onError?.(error);
-          controller.error(error);
+    // Try to render error using router state's error handler
+    const errorHtml = this.renderErrorToString(
+      error instanceof Error ? error : new Error(String(error)),
+      routerState,
+    );
+    controller.enqueue(encoder.encode(errorHtml));
+    // Close root div
+    controller.enqueue(slots.rootClose);
+    // Content after root (if any)
+    if (!streamState.bodyStarted && slots.afterRoot) {
+      controller.enqueue(encoder.encode(slots.afterRoot));
+    }
+    // Close document
+    controller.enqueue(slots.scriptClose);
+  }
+  /**
+   * Render an error to HTML string using the router's error handler.
+   *
+   * Falls back to ErrorViewer if:
+   * - No router state is available
+   * - The error handler returns null/undefined
+   * - The error handler itself throws
+   */
+  protected renderErrorToString(
+    error: Error,
+    routerState: ReactRouterState | undefined,
+  ): string {
+    // Log the error with stack trace for debugging
+    this.log.error("SSR rendering error", error);
+    let errorElement: ReactNode;
+    // Try to use the router state's error handler
+    if (routerState?.onError) {
+      try {
+        const result = routerState.onError(error, routerState);
+        // If handler returns a Redirection, we can't handle it (headers already sent)
+        // Log and fall through to default error viewer
+        if (result instanceof Redirection) {
+          this.log.warn(
+            "Error handler returned Redirection but headers already sent",
+            { redirect: result.redirect },
+          );
+        } else if (result !== null && result !== undefined) {
+          errorElement = result;
         }
-      },
-    });
+      } catch (handlerError) {
+        this.log.error("Error handler threw an exception", handlerError);
+        // Fall through to default error viewer
+      }
+    }
+    // Fall back to ErrorViewer if no element was produced
+    if (!errorElement) {
+      errorElement = createElement(ErrorViewer, {
+        error,
+        alepha: this.alepha,
+      });
+    }
+    // Wrap in AlephaContext.Provider so any components that need it can access it
+    const wrappedElement = createElement(
+      AlephaContext.Provider,
+      { value: this.alepha },
+      errorElement,
+    );
+    try {
+      return renderToString(wrappedElement);
+    } catch (renderError) {
+      // If renderToString fails, return minimal fallback HTML
+      this.log.error("Failed to render error component", renderError);
+      return error.message;
+    }
   }
 }
 // ---------------------------------------------------------------------------------------------------------------------
 /**