@alepha/react 0.14.2 → 0.14.3

package/src/head/__tests__/seo-head.spec.ts

@@ -0,0 +1,121 @@
+import { $page } from "@alepha/react/router";
+import { Alepha } from "alepha";
+import { describe, it } from "vitest";
+import { $head, AlephaReactHead } from "../index.ts";
+
+class App {
+  head = $head({
+    title: "Alepha Framework",
+    description: "TypeScript framework made easy",
+    image: "https://alepha.dev/og-image.png",
+    url: "https://alepha.dev/",
+    siteName: "Alepha",
+    locale: "en_US",
+    type: "website",
+    imageWidth: 1200,
+    imageHeight: 630,
+    twitter: {
+      card: "summary_large_image",
+    },
+  });
+
+  home = $page({
+    component: () => "Home",
+  });
+}
+
+const alepha = Alepha.create().with(AlephaReactHead);
+const a = alepha.inject(App);
+
+describe("SEO Head", () => {
+  it("should render page with SEO meta tags", async ({ expect }) => {
+    const result = await a.home.render({ html: true, hydration: false });
+
+    // Should include description
+    expect(result.html).toContain(
+      '<meta name="description" content="TypeScript framework made easy">',
+    );
+
+    // Should include OpenGraph tags with property attribute
+    expect(result.html).toContain(
+      '<meta property="og:title" content="Alepha Framework">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:description" content="TypeScript framework made easy">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:image" content="https://alepha.dev/og-image.png">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:url" content="https://alepha.dev/">',
+    );
+    expect(result.html).toContain('<meta property="og:type" content="website">');
+    expect(result.html).toContain(
+      '<meta property="og:site_name" content="Alepha">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:locale" content="en_US">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:image:width" content="1200">',
+    );
+    expect(result.html).toContain(
+      '<meta property="og:image:height" content="630">',
+    );
+
+    // Should include Twitter Card tags with name attribute
+    expect(result.html).toContain(
+      '<meta name="twitter:card" content="summary_large_image">',
+    );
+    expect(result.html).toContain(
+      '<meta name="twitter:title" content="Alepha Framework">',
+    );
+    expect(result.html).toContain(
+      '<meta name="twitter:description" content="TypeScript framework made easy">',
+    );
+    expect(result.html).toContain(
+      '<meta name="twitter:image" content="https://alepha.dev/og-image.png">',
+    );
+
+    // Should include canonical link
+    expect(result.html).toContain(
+      '<link rel="canonical" href="https://alepha.dev/">',
+    );
+  });
+});
+
+class AppWithPageSeo {
+  head = $head({
+    title: "My Site",
+    titleSeparator: " | ",
+  });
+
+  blog = $page({
+    path: "/blog",
+    head: {
+      title: "Blog",
+      description: "Read our latest articles",
+      image: "https://example.com/blog-og.png",
+      type: "article",
+    },
+    component: () => "Blog",
+  });
+}
+
+const alepha2 = Alepha.create().with(AlephaReactHead);
+const app2 = alepha2.inject(AppWithPageSeo);
+
+describe("SEO Head on Page", () => {
+  it("should render page-level SEO", async ({ expect }) => {
+    const result = await app2.blog.render({ html: true, hydration: false });
+
+    expect(result.html).toContain("<title>Blog | My Site</title>");
+    expect(result.html).toContain(
+      '<meta name="description" content="Read our latest articles">',
+    );
+    expect(result.html).toContain('<meta property="og:type" content="article">');
+    expect(result.html).toContain(
+      '<meta property="og:image" content="https://example.com/blog-og.png">',
+    );
+  });
+});

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

@@ -9,6 +9,7 @@ import { $head } from "./primitives/$head.ts";
 import type { Head } from "./interfaces/Head.ts";
 import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
 import { HeadProvider } from "./providers/HeadProvider.ts";
+import { SeoExpander } from "./helpers/SeoExpander.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -54,5 +55,5 @@ declare module "@alepha/react/router" {
 export const AlephaReactHead = $module({
   name: "alepha.react.head",
   primitives: [$head],
-  services: [AlephaReact, ServerHeadProvider, HeadProvider],
+  services: [AlephaReact, ServerHeadProvider, HeadProvider, SeoExpander],
 });

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

@@ -0,0 +1,271 @@
+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 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");
+    });
+  });
+
+  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",
+      });
+    });
+  });
+});