@alepha/react 0.14.2 → 0.14.4

package/src/head/hooks/useHead.spec.tsx

@@ -0,0 +1,288 @@
+import { AlephaContext } from "@alepha/react";
+import type { Head } from "../index.ts";
+import { useHead } from "../index.ts";
+import { render } from "@testing-library/react";
+import { Alepha } from "alepha";
+import { act, type ReactNode } from "react";
+import { beforeEach, describe, it, vi } from "vitest";
+
+/**
+ * @vitest-environment jsdom
+ */
+
+describe("useHead", () => {
+  const renderWithAlepha = (alepha: Alepha, element: ReactNode) => {
+    return render(
+      <AlephaContext.Provider value={alepha}>{element}</AlephaContext.Provider>,
+    );
+  };
+
+  beforeEach(() => {
+    // Reset document state before each test
+    document.title = "";
+    document.head.innerHTML = "";
+    document.body.removeAttribute("class");
+    document.body.removeAttribute("style");
+    document.documentElement.removeAttribute("lang");
+    document.documentElement.removeAttribute("class");
+  });
+
+  it("should set initial head options on mount", ({ expect }) => {
+    const alepha = Alepha.create();
+    const TestComponent = () => {
+      useHead({
+        title: "Test Title",
+      });
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    expect(document.title).toBe("Test Title");
+  });
+
+  it("should return current head state and setter function", ({ expect }) => {
+    const alepha = Alepha.create();
+    let headState: Head;
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [head, setHead] = useHead();
+      headState = head;
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    expect(headState!).toBeDefined();
+    expect(setHeadFn!).toBeDefined();
+    expect(typeof setHeadFn!).toBe("function");
+  });
+
+  it("should update document title when setHead is called", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead();
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    act(() => {
+      setHeadFn({ title: "Updated Title" });
+    });
+
+    expect(document.title).toBe("Updated Title");
+  });
+
+  it("should update meta tags when setHead is called", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead();
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    act(() => {
+      setHeadFn({
+        meta: [
+          { name: "description", content: "Test Description" },
+          { name: "keywords", content: "test, keywords" },
+        ],
+      });
+    });
+
+    const descriptionMeta = document.querySelector('meta[name="description"]');
+    const keywordsMeta = document.querySelector('meta[name="keywords"]');
+
+    expect(descriptionMeta?.getAttribute("content")).toBe("Test Description");
+    expect(keywordsMeta?.getAttribute("content")).toBe("test, keywords");
+  });
+
+  it("should update body attributes when setHead is called", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead();
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    act(() => {
+      setHeadFn({
+        bodyAttributes: {
+          class: "dark-theme",
+          style: "background: black;",
+        },
+      });
+    });
+
+    expect(document.body.getAttribute("class")).toBe("dark-theme");
+    expect(document.body.getAttribute("style")).toBe("background: black;");
+  });
+
+  it("should update html attributes when setHead is called", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead();
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    act(() => {
+      setHeadFn({
+        htmlAttributes: {
+          lang: "en",
+          class: "no-js",
+        },
+      });
+    });
+
+    expect(document.documentElement.getAttribute("lang")).toBe("en");
+    expect(document.documentElement.getAttribute("class")).toBe("no-js");
+  });
+
+  it("should support functional updates", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead({ title: "Initial Title" });
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    expect(document.title).toBe("Initial Title");
+
+    act(() => {
+      setHeadFn((prev) => ({
+        ...prev,
+        title: `${prev?.title} - Updated`,
+      }));
+    });
+
+    expect(document.title).toBe("Initial Title - Updated");
+  });
+
+  it("should handle multiple head updates", ({ expect }) => {
+    const alepha = Alepha.create();
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [, setHead] = useHead();
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    act(() => {
+      setHeadFn({
+        title: "First Title",
+        meta: [{ name: "description", content: "First Description" }],
+      });
+    });
+
+    expect(document.title).toBe("First Title");
+    expect(
+      document
+        .querySelector('meta[name="description"]')
+        ?.getAttribute("content"),
+    ).toBe("First Description");
+
+    act(() => {
+      setHeadFn({
+        title: "Second Title",
+        meta: [{ name: "description", content: "Second Description" }],
+      });
+    });
+
+    expect(document.title).toBe("Second Title");
+    expect(
+      document
+        .querySelector('meta[name="description"]')
+        ?.getAttribute("content"),
+    ).toBe("Second Description");
+  });
+
+  it("should not crash on server-side (non-browser environment)", ({
+    expect,
+  }) => {
+    const alepha = Alepha.create();
+    // Mock isBrowser to return false
+    vi.spyOn(alepha, "isBrowser").mockReturnValue(false);
+
+    let headState: Head;
+    let setHeadFn: (head?: Head | ((previous?: Head) => Head)) => void;
+
+    const TestComponent = () => {
+      const [head, setHead] = useHead({ title: "Server Title" });
+      headState = head;
+      setHeadFn = setHead;
+      return <div>Test</div>;
+    };
+
+    expect(() => {
+      renderWithAlepha(alepha, <TestComponent />);
+    }).not.toThrow();
+
+    expect(headState!).toEqual({});
+
+    // setHead should not crash on server
+    expect(() => {
+      setHeadFn({ title: "New Title" });
+    }).not.toThrow();
+
+    // Document title should remain unchanged on server
+    expect(document.title).toBe("");
+  });
+
+  it("should get current head state from document", ({ expect }) => {
+    const alepha = Alepha.create();
+
+    // Pre-populate document with some head data
+    document.title = "Existing Title";
+    document.body.setAttribute("class", "existing-class");
+    document.documentElement.setAttribute("lang", "fr");
+
+    const meta = document.createElement("meta");
+    meta.setAttribute("name", "author");
+    meta.setAttribute("content", "John Doe");
+    document.head.appendChild(meta);
+
+    let headState: Head;
+
+    const TestComponent = () => {
+      const [head] = useHead();
+      headState = head;
+      return <div>Test</div>;
+    };
+
+    renderWithAlepha(alepha, <TestComponent />);
+
+    expect(headState!.title).toBe("Existing Title");
+    expect(headState!.bodyAttributes?.class).toBe("existing-class");
+    expect(headState!.htmlAttributes?.lang).toBe("fr");
+    expect(headState!.meta).toContainEqual({
+      name: "author",
+      content: "John Doe",
+    });
+  });
+});

package/src/head/index.ts

@@ -1,14 +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";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -17,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";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -54,5 +31,11 @@ declare module "@alepha/react/router" {
 export const AlephaReactHead = $module({
   name: "alepha.react.head",
   primitives: [$head],
-  services: [AlephaReact, ServerHeadProvider, HeadProvider],
+  services: [
+    AlephaReact,
+    BrowserHeadProvider,
+    HeadProvider,
+    SeoExpander,
+    ServerHeadProvider,
+  ],
 });

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

@@ -0,0 +1,196 @@
+import { Alepha } from "alepha";
+import { beforeEach, describe, expect, it } from "vitest";
+import type { Head } from "../interfaces/Head.ts";
+import { BrowserHeadProvider } from "./BrowserHeadProvider.ts";
+
+describe("BrowserHeadProvider", () => {
+  let alepha: Alepha;
+  let provider: BrowserHeadProvider;
+
+  beforeEach(async () => {
+    alepha = Alepha.create();
+    provider = alepha.inject(BrowserHeadProvider);
+
+    // Reset document state
+    document.title = "";
+    document.head.innerHTML = "";
+    document.body.removeAttribute("class");
+    document.body.removeAttribute("style");
+    document.documentElement.removeAttribute("lang");
+    document.documentElement.removeAttribute("class");
+  });
+
+  describe("getHead", () => {
+    it("should return current document head state", () => {
+      document.title = "Test Title";
+      document.body.setAttribute("class", "test-class");
+      document.documentElement.setAttribute("lang", "en");
+
+      const meta = document.createElement("meta");
+      meta.setAttribute("name", "description");
+      meta.setAttribute("content", "Test description");
+      document.head.appendChild(meta);
+
+      const head = provider.getHead(document);
+
+      expect(head.title).toBe("Test Title");
+      expect(head.bodyAttributes?.class).toBe("test-class");
+      expect(head.htmlAttributes?.lang).toBe("en");
+      expect(head.meta).toContainEqual({
+        name: "description",
+        content: "Test description",
+      });
+    });
+
+    it("should handle empty document state", () => {
+      const head = provider.getHead(document);
+
+      expect(head.title).toBe("");
+      expect(head.bodyAttributes).toEqual({});
+      expect(head.htmlAttributes).toEqual({});
+      expect(head.meta).toEqual([]);
+    });
+  });
+
+  describe("renderHead", () => {
+    it("should set document title", () => {
+      const head: Head = { title: "New Title" };
+
+      provider.renderHead(document, head);
+
+      expect(document.title).toBe("New Title");
+    });
+
+    it("should set body attributes", () => {
+      const head: Head = {
+        bodyAttributes: {
+          class: "new-class",
+          style: "background: blue;",
+        },
+      };
+
+      provider.renderHead(document, head);
+
+      expect(document.body.getAttribute("class")).toBe("new-class");
+      expect(document.body.getAttribute("style")).toBe("background: blue;");
+    });
+
+    it("should remove body attributes when value is falsy", () => {
+      document.body.setAttribute("class", "old-class");
+
+      const head: Head = {
+        bodyAttributes: {
+          class: "",
+        },
+      };
+
+      provider.renderHead(document, head);
+
+      expect(document.body.hasAttribute("class")).toBe(false);
+    });
+
+    it("should set html attributes", () => {
+      const head: Head = {
+        htmlAttributes: {
+          lang: "fr",
+          dir: "ltr",
+        },
+      };
+
+      provider.renderHead(document, head);
+
+      expect(document.documentElement.getAttribute("lang")).toBe("fr");
+      expect(document.documentElement.getAttribute("dir")).toBe("ltr");
+    });
+
+    it("should remove html attributes when value is falsy", () => {
+      document.documentElement.setAttribute("lang", "en");
+
+      const head: Head = {
+        htmlAttributes: {
+          lang: "",
+        },
+      };
+
+      provider.renderHead(document, head);
+
+      expect(document.documentElement.hasAttribute("lang")).toBe(false);
+    });
+
+    it("should create new meta tags", () => {
+      const head: Head = {
+        meta: [
+          { name: "description", content: "Test description" },
+          { name: "keywords", content: "test, browser" },
+        ],
+      };
+
+      provider.renderHead(document, head);
+
+      const descriptionMeta = document.querySelector(
+        'meta[name="description"]',
+      );
+      const keywordsMeta = document.querySelector('meta[name="keywords"]');
+
+      expect(descriptionMeta?.getAttribute("content")).toBe("Test description");
+      expect(keywordsMeta?.getAttribute("content")).toBe("test, browser");
+    });
+
+    it("should update existing meta tags", () => {
+      // Pre-populate with existing meta tag
+      const existingMeta = document.createElement("meta");
+      existingMeta.setAttribute("name", "description");
+      existingMeta.setAttribute("content", "Old description");
+      document.head.appendChild(existingMeta);
+
+      const head: Head = {
+        meta: [{ name: "description", content: "New description" }],
+      };
+
+      provider.renderHead(document, head);
+
+      const descriptionMeta = document.querySelector(
+        'meta[name="description"]',
+      );
+      expect(descriptionMeta?.getAttribute("content")).toBe("New description");
+      expect(
+        document.querySelectorAll('meta[name="description"]'),
+      ).toHaveLength(1);
+    });
+
+    it("should handle complete head object", () => {
+      const head: Head = {
+        title: "Complete Test",
+        htmlAttributes: {
+          lang: "es",
+          class: "theme-dark",
+        },
+        bodyAttributes: {
+          class: "page-test",
+          "data-theme": "dark",
+        },
+        meta: [
+          { name: "description", content: "Complete test page" },
+          { name: "author", content: "Test Author" },
+        ],
+      };
+
+      provider.renderHead(document, head);
+
+      expect(document.title).toBe("Complete Test");
+      expect(document.documentElement.getAttribute("lang")).toBe("es");
+      expect(document.documentElement.getAttribute("class")).toBe("theme-dark");
+      expect(document.body.getAttribute("class")).toBe("page-test");
+      expect(document.body.getAttribute("data-theme")).toBe("dark");
+
+      const descriptionMeta = document.querySelector(
+        'meta[name="description"]',
+      );
+      const authorMeta = document.querySelector('meta[name="author"]');
+      expect(descriptionMeta?.getAttribute("content")).toBe(
+        "Complete test page",
+      );
+      expect(authorMeta?.getAttribute("content")).toBe("Test Author");
+    });
+  });
+});

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 {