@alepha/react 0.14.3 → 0.15.0

package/dist/websocket/index.d.ts

@@ -2,54 +2,53 @@ import { ChannelPrimitive, TWSObject } from "alepha/websocket";
 import { Static } from "alepha";
 
 //#region ../../src/websocket/hooks/useRoom.d.ts
-
 /**
  * UseRoom options
  */
 interface UseRoomOptions<TClient extends TWSObject, TServer extends TWSObject> {
   /**
-   * Room ID to connect to
-   */
+       * Room ID to connect to
+       */
   roomId: string;
   /**
-   * Channel primitive defining the schemas
-   */
+       * Channel primitive defining the schemas
+       */
   channel: ChannelPrimitive<TClient, TServer>;
   /**
-   * Handler for incoming messages from the server
-   */
+       * Handler for incoming messages from the server
+       */
   handler: (message: Static<TClient>) => void;
   /**
-   * Optional WebSocket URL override
-   * Defaults to auto-detected URL based on window.location
-   */
+       * Optional WebSocket URL override
+       * Defaults to auto-detected URL based on window.location
+       */
   url?: string;
   /**
-   * Enable automatic reconnection on disconnect
-   * @default true
-   */
+       * Enable automatic reconnection on disconnect
+       * @default true
+       */
   autoReconnect?: boolean;
   /**
-   * Reconnection interval in milliseconds
-   * @default 3000
-   */
+       * Reconnection interval in milliseconds
+       * @default 3000
+       */
   reconnectInterval?: number;
   /**
-   * Maximum reconnection attempts (-1 for infinite)
-   * @default 10
-   */
+       * Maximum reconnection attempts (-1 for infinite)
+       * @default 10
+       */
   maxReconnectAttempts?: number;
   /**
-   * Called when connection is established
-   */
+       * Called when connection is established
+       */
   onConnect?: () => void;
   /**
-   * Called when connection is closed
-   */
+       * Called when connection is closed
+       */
   onDisconnect?: () => void;
   /**
-   * Called on connection error
-   */
+       * Called on connection error
+       */
   onError?: (error: Error) => void;
 }
 /**
@@ -57,32 +56,32 @@ interface UseRoomOptions<TClient extends TWSObject, TServer extends TWSObject> {
  */
 interface UseRoomReturn<TServer extends TWSObject> {
   /**
-   * Send a message to the server
-   */
+       * Send a message to the server
+       */
   send: (message: Static<TServer>) => Promise<void>;
   /**
-   * Whether the connection is established
-   */
+       * Whether the connection is established
+       */
   isConnected: boolean;
   /**
-   * Whether the connection is in progress
-   */
+       * Whether the connection is in progress
+       */
   isConnecting: boolean;
   /**
-   * Whether there was an error
-   */
+       * Whether there was an error
+       */
   isError: boolean;
   /**
-   * The error object if any
-   */
+       * The error object if any
+       */
   error?: Error;
   /**
-   * Manually reconnect
-   */
+       * Manually reconnect
+       */
   reconnect: () => void;
   /**
-   * Manually disconnect
-   */
+       * Manually disconnect
+       */
   disconnect: () => void;
 }
 /**

package/dist/websocket/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/websocket/hooks/useRoom.tsx"],"sourcesContent":[],"mappings":";;;;;;;AASA;AACkB,UADD,cACC,CAAA,gBAAA,SAAA,EAAA,gBACA,SADA,CAAA,CAAA;EACA;;;EAUP,MAAA,EAAA,MAAA;EAKiB;;;EAuCH,OAAA,EA5Cd,gBA4Cc,CA5CG,OA4CH,EA5CY,OA4CZ,CAAA;EAMR;;;EAIC,OAAA,EAAA,CAAA,OAAA,EAjDG,MAiDH,CAjDU,OAiDV,CAAA,EAAA,GAAA,IAAA;EAAoB;;;AA4DtC;EAAwC,GAAA,CAAA,EAAA,MAAA;EAA2B;;;;EAGlD,aAAA,CAAA,EAAA,OAAA;EAAd;;;;;;;;;;;;;;;;;;;;;oBAzEiB;;;;;UAMH,8BAA8B;;;;kBAI7B,OAAO,aAAa;;;;;;;;;;;;;;;;UAoB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAwCG,0BAA2B,2BAA2B,oBACxD,eAAe,SAAS,8BAEhC,cAAc"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/websocket/hooks/useRoom.tsx"],"mappings":";;;;;AASA;;UAAiB,cAAA,iBACC,SAAA,kBACA,SAAA;EAAA;;;EAAA,MAAA;EAAA;;;EAAA,OAAA,EAUP,gBAAA,CAAiB,OAAA,EAAS,OAAA;EAAA;;;EAAA,OAAA,GAAA,OAAA,EAKhB,MAAA,CAAO,OAAA;EAAA;;;;EAAA,GAAA;EAAA;;;;EAAA,aAAA;EAAA;;;;EAAA,iBAAA;EAAA;;;;EAAA,oBAAA;EAAA;;;EAAA,SAAA;EAAA;;;EAAA,YAAA;EAAA;;;EAAA,OAAA,IAAA,KAAA,EAuCR,KAAA;AAAA;AAAA;;AAMpB;AANoB,UAMH,aAAA,iBAA8B,SAAA;EAAA;;;EAAA,IAAA,GAAA,OAAA,EAI7B,MAAA,CAAO,OAAA,MAAa,OAAA;EAAA;;;EAAA,WAAA;EAAA;;;EAAA,YAAA;EAAA;;;EAAA,OAAA;EAAA;;;EAAA,KAAA,GAoB5B,KAAA;EAAA;;AAwCV;EAxCU,SAAA;EAAA;;AAwCV;EAxCU,UAAA;AAAA;AAAA;;AAwCV;;;;;;;;;;;;;;;;;;;;;;;;;AAxCU,cAwCG,OAAA,mBAA2B,SAAA,kBAA2B,SAAA,EAAA,OAAA,EACxD,cAAA,CAAe,OAAA,EAAS,OAAA,GAAA,IAAA,gBAEhC,aAAA,CAAc,OAAA"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@alepha/react",
   "description": "React components and hooks for building Alepha applications.",
   "author": "Nicolas Foures",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -25,19 +25,19 @@
     "@testing-library/react": "^16.3.1",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "alepha": "0.14.3",
+    "alepha": "0.15.0",
     "jsdom": "^27.4.0",
     "react": "^19.2.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "alepha": "0.14.3",
+    "alepha": "0.15.0",
     "react": "^19"
   },
   "scripts": {
     "lint": "alepha lint",
-    "check": "alepha typecheck",
+    "typecheck": "alepha typecheck",
     "test": "vitest run",
     "build": "node scripts/build.ts"
   },

package/src/auth/__tests__/$auth.spec.ts

@@ -1,10 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
-import { $realm } from "alepha/security";
-import { HttpClient, ServerProvider } from "alepha/server";
+import { $issuer, AlephaSecurity } from "alepha/security";
+import { AlephaServer, HttpClient, ServerProvider } from "alepha/server";
 import { $client } from "alepha/server/links";
-import { AlephaServerSecurity } from "alepha/server/security";
 import { describe, test } from "vitest";
 import {
   $auth,
@@ -25,7 +24,7 @@ describe("$auth", () => {
     };
 
     class App {
-      realm = $realm({
+      issuer = $issuer({
         secret: "my-secret-key",
         roles: [
           {
@@ -36,7 +35,7 @@ describe("$auth", () => {
       });
 
       auth = $auth({
-        realm: this.realm,
+        issuer: this.issuer,
         credentials: {
           account: () => user,
         },
@@ -94,7 +93,7 @@ describe("$auth", () => {
         );
 
     test("should login with credentials", async ({ expect }) => {
-      const alepha = Alepha.create().with(App).with(AlephaServerSecurity);
+      const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity).with(App);
       const auth = alepha.inject(ReactAuth);
       await alepha.start();
 
@@ -113,7 +112,7 @@ describe("$auth", () => {
     });
 
     test("should get userinfo", async ({ expect }) => {
-      const alepha = Alepha.create().with(App).with(AlephaServerSecurity);
+      const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity).with(App);
       await alepha.start();
 
       const { data: tokens } = await login(alepha);
@@ -134,7 +133,7 @@ describe("$auth", () => {
     });
 
     test("should reject expired token", async ({ expect }) => {
-      const alepha = Alepha.create().with(App);
+      const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity).with(App);
       await alepha.start();
 
       const { data: tokens } = await login(alepha);
@@ -150,7 +149,7 @@ describe("$auth", () => {
     });
 
     test("should refresh expired token", async ({ expect }) => {
-      const alepha = Alepha.create().with(App);
+      const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity).with(App);
       await alepha.start();
 
       const { data: tokens } = await login(alepha);
@@ -174,7 +173,7 @@ describe("$auth", () => {
     });
 
     test("should reject expired refresh token", async ({ expect }) => {
-      const alepha = Alepha.create().with(App);
+      const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity).with(App);
       await alepha.start();
 
       const { data: tokens } = await login(alepha);
@@ -182,7 +181,7 @@ describe("$auth", () => {
       await alepha.inject(DateTimeProvider).travel(40, "days");
 
       await expect(refresh(alepha, tokens)).rejects.toThrowError(
-        "Failed to refresh access token using the refresh token (realm)",
+        "Failed to refresh access token using the refresh token (issuer)",
       );
     });
 });

package/src/core/__tests__/Router.spec.tsx

@@ -74,7 +74,7 @@ test("Router - NestedView", async ({ expect }) => {
             name: t.text(),
           }),
         },
-        resolve: ({ params }) => params,
+        loader: ({ params }) => params,
         component: (props) => `Hello, ${props.name}!`,
       },
     ],
@@ -125,18 +125,18 @@ test("Router - All routes", async ({ expect }) => {
           {
             path: ":id",
             schema: { params: t.object({ id: t.text() }) },
-            resolve: ({ params }) => {
+            loader: ({ params }) => {
               if (params.id === "boom") throw new Error("boom");
               return params;
             },
             children: [
               {
-                resolve: ({ params }) => params,
+                loader: ({ params }) => params,
                 component: ({ id }) => `hey ${id}`,
               },
               {
                 path: "profile",
-                resolve: ({ params }) => params,
+                loader: ({ params }) => params,
                 component: ({ id }) => `profile of ${id}`,
               },
             ],

package/src/head/{__tests__/expandSeo.spec.ts → helpers/SeoExpander.spec.ts}

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { describe, it } from "vitest";
-import { SeoExpander } from "../helpers/SeoExpander.ts";
+import { SeoExpander } from "./SeoExpander.ts";
 
 describe("SeoExpander", () => {
   it("should expand basic SEO configuration", ({ expect }) => {

package/src/head/index.ts

@@ -1,15 +1,10 @@
 import { AlephaReact } from "@alepha/react";
-import type {
-  PageConfigSchema,
-  TPropsDefault,
-  TPropsParentDefault,
-} from "@alepha/react/router";
 import { $module } from "alepha";
 import { $head } from "./primitives/$head.ts";
-import type { Head } from "./interfaces/Head.ts";
-import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
+import { BrowserHeadProvider } from "./providers/BrowserHeadProvider.ts";
 import { HeadProvider } from "./providers/HeadProvider.ts";
 import { SeoExpander } from "./helpers/SeoExpander.ts";
+import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -18,26 +13,7 @@ export * from "./hooks/useHead.ts";
 export * from "./interfaces/Head.ts";
 export * from "./helpers/SeoExpander.ts";
 export * from "./providers/ServerHeadProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-// Augment PagePrimitiveOptions in router module
-declare module "@alepha/react/router" {
-  interface PagePrimitiveOptions<
-    TConfig extends PageConfigSchema = PageConfigSchema,
-    TProps extends object = TPropsDefault,
-    TPropsParent extends object = TPropsParentDefault,
-  > {
-    head?: Head | ((props: TProps, previous?: Head) => Head);
-  }
-}
-
-// Augment ReactRouterState in router module
-declare module "@alepha/react/router" {
-  interface ReactRouterState {
-    head: Head;
-  }
-}
+export * from "./providers/BrowserHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -55,5 +31,11 @@ declare module "@alepha/react/router" {
 export const AlephaReactHead = $module({
   name: "alepha.react.head",
   primitives: [$head],
-  services: [AlephaReact, ServerHeadProvider, HeadProvider, SeoExpander],
+  services: [
+    AlephaReact,
+    BrowserHeadProvider,
+    HeadProvider,
+    SeoExpander,
+    ServerHeadProvider,
+  ],
 });

package/src/head/providers/BrowserHeadProvider.browser.spec.ts

@@ -1,7 +1,5 @@
-import { $page } from "@alepha/react/router";
 import { Alepha } from "alepha";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { AlephaReactHead } from "../index.browser.ts";
+import { beforeEach, describe, expect, it } from "vitest";
 import type { Head } from "../interfaces/Head.ts";
 import { BrowserHeadProvider } from "./BrowserHeadProvider.ts";
 
@@ -195,77 +193,4 @@ describe("BrowserHeadProvider", () => {
       expect(authorMeta?.getAttribute("content")).toBe("Test Author");
     });
   });
-
-  describe("$page integration", () => {
-    class TestApp {
-      simplePage = $page({
-        path: "/",
-        head: {
-          title: "Simple Page",
-          bodyAttributes: { class: "simple-page" },
-        },
-        component: () => "Simple content",
-      });
-
-      complexPage = $page({
-        path: "/complex",
-        head: {
-          title: "Complex Page",
-          htmlAttributes: {
-            lang: "en",
-            "data-theme": "dark",
-          },
-          bodyAttributes: {
-            class: "complex-page",
-            style: "background: black;",
-          },
-          meta: [
-            { name: "description", content: "Complex test page" },
-            {
-              name: "viewport",
-              content: "width=device-width, initial-scale=1",
-            },
-          ],
-        },
-        component: () => "Complex content",
-      });
-    }
-
-    afterEach(() => {
-      document.body.querySelector("#root")?.remove();
-    });
-
-    it("should render simple page head configuration", async () => {
-      const alepha = Alepha.create().with(AlephaReactHead).with(TestApp);
-      await alepha.start();
-
-      expect(document.title).toBe("Simple Page");
-      expect(document.body.getAttribute("class")).toBe("simple-page");
-    });
-
-    it("should get current head state and match page configuration", async () => {
-      const alepha = Alepha.create().with(AlephaReactHead);
-      const app = alepha.inject(TestApp);
-      await alepha.start();
-
-      // Apply complex page head
-      const headConfig = app.complexPage.options.head as Head;
-      provider.renderHead(document, headConfig);
-
-      // Get current head state
-      const currentHead = provider.getHead(document);
-
-      expect(currentHead.title).toBe(headConfig.title);
-      expect(currentHead.htmlAttributes?.lang).toBe(
-        headConfig.htmlAttributes?.lang,
-      );
-      expect(currentHead.bodyAttributes?.class).toBe(
-        headConfig.bodyAttributes?.class,
-      );
-      expect(currentHead.meta).toContainEqual({
-        name: "description",
-        content: "Complex test page",
-      });
-    });
-  });
 });

package/src/head/providers/BrowserHeadProvider.ts

@@ -1,33 +1,39 @@
-import { $hook, $inject } from "alepha";
+import { $inject, Alepha } from "alepha";
 import type { Head, HeadMeta } from "../interfaces/Head.ts";
 import { HeadProvider } from "./HeadProvider.ts";
 
+/**
+ * Browser-side head provider that manages document head elements.
+ *
+ * Used by ReactBrowserProvider and ReactBrowserRouterProvider to update
+ * document title, meta tags, and other head elements during client-side
+ * navigation.
+ */
 export class BrowserHeadProvider {
+  protected readonly alepha = $inject(Alepha);
   protected readonly headProvider = $inject(HeadProvider);
 
   protected get document(): Document {
     return window.document;
   }
 
-  protected readonly onBrowserRender = $hook({
-    on: "react:browser:render",
-    handler: async ({ state }) => {
-      this.headProvider.fillHead(state);
-      if (state.head) {
-        this.renderHead(this.document, state.head);
-      }
-    },
-  });
+  /**
+   * Fill head state from route configurations and render to document.
+   * Combines fillHead from HeadProvider with renderHead to the DOM.
+   *
+   * Only runs in browser environment - no-op on server.
+   */
+  public fillAndRenderHead(state: { head: Head; layers: Array<any> }): void {
+    // Skip on server-side
+    if (!this.alepha.isBrowser()) {
+      return;
+    }
 
-  protected readonly onTransitionEnd = $hook({
-    on: "react:transition:end",
-    handler: async ({ state }) => {
-      this.headProvider.fillHead(state);
-      if (state.head) {
-        this.renderHead(this.document, state.head);
-      }
-    },
-  });
+    this.headProvider.fillHead(state as any);
+    if (state.head) {
+      this.renderHead(this.document, state.head);
+    }
+  }
 
   public getHead(document: Document): Head {
     return {

package/src/head/providers/HeadProvider.ts

@@ -1,14 +1,54 @@
-import type { PageRoute, ReactRouterState } from "@alepha/react/router";
 import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
 import { SeoExpander } from "../helpers/SeoExpander.ts";
 import type { Head } from "../interfaces/Head.ts";
 
+/**
+ * Provides methods to fill and merge head information into the application state.
+ *
+ * Used both on server and client side to manage document head.
+ *
+ * @see {@link SeoExpander}
+ * @see {@link ServerHeadProvider}
+ * @see {@link BrowserHeadProvider}
+ */
 export class HeadProvider {
+  protected readonly log = $logger();
   protected readonly seoExpander = $inject(SeoExpander);
 
   public global?: Array<Head | (() => Head)> = [];
 
-  public fillHead(state: ReactRouterState) {
+  /**
+   * Track if we've warned about page-level htmlAttributes to avoid spam.
+   */
+  protected warnedAboutHtmlAttributes = false;
+
+  /**
+   * Resolve global head configuration (from $head primitives only).
+   *
+   * This is used to get htmlAttributes early, before page loaders run.
+   * Only htmlAttributes from global $head are allowed; page-level htmlAttributes
+   * are ignored for early streaming optimization.
+   *
+   * @returns Merged global head with htmlAttributes
+   */
+  public resolveGlobalHead(): Head {
+    const head: Head = {};
+
+    for (const h of this.global ?? []) {
+      const resolved = typeof h === "function" ? h() : h;
+      if (resolved.htmlAttributes) {
+        head.htmlAttributes = {
+          ...head.htmlAttributes,
+          ...resolved.htmlAttributes,
+        };
+      }
+    }
+
+    return head;
+  }
+
+  public fillHead(state: HeadState) {
     state.head = {
       ...state.head,
     };
@@ -25,7 +65,7 @@ export class HeadProvider {
     }
   }
 
-  protected mergeHead(state: ReactRouterState, head: Head): void {
+  protected mergeHead(state: HeadState, head: Head): void {
     // Expand SEO fields into meta tags
     const { meta, link } = this.seoExpander.expand(head);
     state.head = {
@@ -38,8 +78,8 @@ export class HeadProvider {
   }
 
   protected fillHeadByPage(
-    page: PageRoute,
-    state: ReactRouterState,
+    page: HeadRoute,
+    state: HeadState,
     props: Record<string, any>,
   ): void {
     if (!page.head) {
@@ -70,11 +110,14 @@ export class HeadProvider {
       state.head.titleSeparator = head.titleSeparator;
     }
 
-    if (head.htmlAttributes) {
-      state.head.htmlAttributes = {
-        ...state.head.htmlAttributes,
-        ...head.htmlAttributes,
-      };
+    // htmlAttributes from pages are ignored for early streaming optimization.
+    // Only global $head can set htmlAttributes.
+    if (head.htmlAttributes && !this.warnedAboutHtmlAttributes) {
+      this.warnedAboutHtmlAttributes = true;
+      this.log.warn(
+        "Page-level htmlAttributes are ignored. Use global $head() for htmlAttributes instead, " +
+          "as they are sent before page loaders run for early streaming optimization.",
+      );
     }
 
     if (head.bodyAttributes) {
@@ -97,3 +140,26 @@ export class HeadProvider {
     }
   }
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Minimal route interface for head processing.
+ * Avoids circular dependency with @alepha/react/router.
+ */
+interface HeadRoute {
+  head?: Head | ((props: Record<string, any>, previous?: Head) => Head);
+}
+
+/**
+ * Minimal state interface for head processing.
+ * Avoids circular dependency with @alepha/react/router.
+ */
+interface HeadState {
+  head: Head;
+  layers: Array<{
+    route?: HeadRoute;
+    props?: Record<string, any>;
+    error?: Error;
+  }>;
+}