alepha 0.15.1 → 0.15.3

package/src/react/head/helpers/SeoExpander.spec.ts

@@ -0,0 +1,203 @@
+import { Alepha } from "alepha";
+import { describe, it } from "vitest";
+import { SeoExpander } from "./SeoExpander.ts";
+
+describe("SeoExpander", () => {
+  it("should expand basic SEO configuration", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({
+      title: "My App",
+      description: "Build amazing apps",
+      url: "https://example.com/",
+    });
+
+    expect(result.meta).toContainEqual({
+      name: "description",
+      content: "Build amazing apps",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:title",
+      content: "My App",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:description",
+      content: "Build amazing apps",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:url",
+      content: "https://example.com/",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:type",
+      content: "website",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:title",
+      content: "My App",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:description",
+      content: "Build amazing apps",
+    });
+    expect(result.link).toContainEqual({
+      rel: "canonical",
+      href: "https://example.com/",
+    });
+  });
+
+  it("should expand full SEO configuration with image", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({
+      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,
+      imageAlt: "Alepha Framework Logo",
+    });
+
+    // OpenGraph tags
+    expect(result.meta).toContainEqual({
+      property: "og:image",
+      content: "https://alepha.dev/og-image.png",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:image:width",
+      content: "1200",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:image:height",
+      content: "630",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:image:alt",
+      content: "Alepha Framework Logo",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:site_name",
+      content: "Alepha",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:locale",
+      content: "en_US",
+    });
+
+    // Twitter tags
+    expect(result.meta).toContainEqual({
+      name: "twitter:image",
+      content: "https://alepha.dev/og-image.png",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:image:alt",
+      content: "Alepha Framework Logo",
+    });
+    // With image, default to summary_large_image
+    expect(result.meta).toContainEqual({
+      name: "twitter:card",
+      content: "summary_large_image",
+    });
+  });
+
+  it("should support Twitter-specific overrides", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({
+      title: "Base Title",
+      description: "Base description",
+      twitter: {
+        card: "summary",
+        site: "@alepha_dev",
+        creator: "@johndoe",
+        title: "Twitter-specific Title",
+      },
+    });
+
+    expect(result.meta).toContainEqual({
+      name: "twitter:card",
+      content: "summary",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:site",
+      content: "@alepha_dev",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:creator",
+      content: "@johndoe",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:title",
+      content: "Twitter-specific Title",
+    });
+    // OG should still use base title
+    expect(result.meta).toContainEqual({
+      property: "og:title",
+      content: "Base Title",
+    });
+  });
+
+  it("should support OpenGraph-specific overrides", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({
+      title: "Base Title",
+      description: "Base description",
+      og: {
+        title: "OG-specific Title",
+        description: "OG-specific description",
+      },
+    });
+
+    expect(result.meta).toContainEqual({
+      property: "og:title",
+      content: "OG-specific Title",
+    });
+    expect(result.meta).toContainEqual({
+      property: "og:description",
+      content: "OG-specific description",
+    });
+    // Twitter should use base
+    expect(result.meta).toContainEqual({
+      name: "twitter:title",
+      content: "Base Title",
+    });
+    expect(result.meta).toContainEqual({
+      name: "twitter:description",
+      content: "Base description",
+    });
+  });
+
+  it("should handle article type", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({
+      title: "Blog Post",
+      type: "article",
+    });
+
+    expect(result.meta).toContainEqual({
+      property: "og:type",
+      content: "article",
+    });
+  });
+
+  it("should return empty arrays for empty config", ({ expect }) => {
+    const alepha = Alepha.create();
+    const seoExpander = alepha.inject(SeoExpander);
+
+    const result = seoExpander.expand({});
+
+    expect(result.meta).toEqual([]);
+    expect(result.link).toEqual([]);
+  });
+});

package/src/react/head/helpers/SeoExpander.ts

@@ -0,0 +1,142 @@
+import type { Head, HeadMeta } from "../interfaces/Head.ts";
+
+/**
+ * Expands Head configuration into SEO meta tags.
+ *
+ * Generates:
+ * - `<meta name="description">` from head.description
+ * - `<meta property="og:*">` OpenGraph tags
+ * - `<meta name="twitter:*">` Twitter Card tags
+ *
+ * @example
+ * ```ts
+ * const helper = new SeoExpander();
+ * const { meta, link } = helper.expand({
+ *   title: "My App",
+ *   description: "Build amazing apps",
+ *   image: "https://example.com/og.png",
+ *   url: "https://example.com/",
+ * });
+ * ```
+ */
+export class SeoExpander {
+  public expand(head: Head): {
+    meta: HeadMeta[];
+    link: Array<{ rel: string; href: string }>;
+  } {
+    const meta: HeadMeta[] = [];
+    const link: Array<{ rel: string; href: string }> = [];
+
+    // Only expand SEO if there's meaningful content beyond just title
+    const hasSeoContent =
+      head.description ||
+      head.image ||
+      head.url ||
+      head.siteName ||
+      head.locale ||
+      head.type ||
+      head.og ||
+      head.twitter;
+
+    if (!hasSeoContent) {
+      return { meta, link };
+    }
+
+    // Base description
+    if (head.description) {
+      meta.push({ name: "description", content: head.description });
+    }
+
+    // Canonical URL
+    if (head.url) {
+      link.push({ rel: "canonical", href: head.url });
+    }
+
+    // OpenGraph tags
+    this.expandOpenGraph(head, meta);
+
+    // Twitter Card tags
+    this.expandTwitter(head, meta);
+
+    return { meta, link };
+  }
+
+  protected expandOpenGraph(head: Head, meta: HeadMeta[]): void {
+    const ogTitle = head.og?.title ?? head.title;
+    const ogDescription = head.og?.description ?? head.description;
+    const ogImage = head.og?.image ?? head.image;
+
+    if (head.type || ogTitle) {
+      meta.push({ property: "og:type", content: head.type ?? "website" });
+    }
+    if (head.url) {
+      meta.push({ property: "og:url", content: head.url });
+    }
+    if (ogTitle) {
+      meta.push({ property: "og:title", content: ogTitle });
+    }
+    if (ogDescription) {
+      meta.push({ property: "og:description", content: ogDescription });
+    }
+    if (ogImage) {
+      meta.push({ property: "og:image", content: ogImage });
+      if (head.imageWidth) {
+        meta.push({
+          property: "og:image:width",
+          content: String(head.imageWidth),
+        });
+      }
+      if (head.imageHeight) {
+        meta.push({
+          property: "og:image:height",
+          content: String(head.imageHeight),
+        });
+      }
+      if (head.imageAlt) {
+        meta.push({ property: "og:image:alt", content: head.imageAlt });
+      }
+    }
+    if (head.siteName) {
+      meta.push({ property: "og:site_name", content: head.siteName });
+    }
+    if (head.locale) {
+      meta.push({ property: "og:locale", content: head.locale });
+    }
+  }
+
+  protected expandTwitter(head: Head, meta: HeadMeta[]): void {
+    const twitterTitle = head.twitter?.title ?? head.title;
+    const twitterDescription = head.twitter?.description ?? head.description;
+    const twitterImage = head.twitter?.image ?? head.image;
+
+    if (head.twitter?.card || twitterTitle || twitterImage) {
+      meta.push({
+        name: "twitter:card",
+        content:
+          head.twitter?.card ??
+          (twitterImage ? "summary_large_image" : "summary"),
+      });
+    }
+    if (head.url) {
+      meta.push({ name: "twitter:url", content: head.url });
+    }
+    if (twitterTitle) {
+      meta.push({ name: "twitter:title", content: twitterTitle });
+    }
+    if (twitterDescription) {
+      meta.push({ name: "twitter:description", content: twitterDescription });
+    }
+    if (twitterImage) {
+      meta.push({ name: "twitter:image", content: twitterImage });
+      if (head.imageAlt) {
+        meta.push({ name: "twitter:image:alt", content: head.imageAlt });
+      }
+    }
+    if (head.twitter?.site) {
+      meta.push({ name: "twitter:site", content: head.twitter.site });
+    }
+    if (head.twitter?.creator) {
+      meta.push({ name: "twitter:creator", content: head.twitter.creator });
+    }
+  }
+}

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

@@ -0,0 +1,288 @@
+import { render } from "@testing-library/react";
+import { Alepha } from "alepha";
+import { AlephaContext } from "alepha/react";
+import { act, type ReactNode } from "react";
+import { beforeEach, describe, it, vi } from "vitest";
+import type { Head } from "../index.ts";
+import { useHead } from "../index.ts";
+
+/**
+ * @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/react/head/hooks/useHead.ts

@@ -0,0 +1,62 @@
+import { Alepha } from "alepha";
+import { useInject } from "alepha/react";
+import { useCallback, useEffect, useMemo } from "react";
+import type { Head } from "../interfaces/Head.ts";
+import { BrowserHeadProvider } from "../providers/BrowserHeadProvider.ts";
+
+/**
+ * ```tsx
+ * const App = () => {
+ *   const [head, setHead] = useHead({
+ *     // will set the document title on the first render
+ *     title: "My App",
+ *   });
+ *
+ *   return (
+ *     // This will update the document title when the button is clicked
+ *     <button onClick={() => setHead({ title: "Change Title" })}>
+ *       Change Title {head.title}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export const useHead = (options?: UseHeadOptions): UseHeadReturn => {
+  const alepha = useInject(Alepha);
+
+  const current = useMemo(() => {
+    if (!alepha.isBrowser()) {
+      return {};
+    }
+
+    return alepha.inject(BrowserHeadProvider).getHead(window.document);
+  }, []);
+
+  const setHead = useCallback((head?: Head | ((previous?: Head) => Head)) => {
+    if (!alepha.isBrowser()) {
+      return;
+    }
+
+    alepha
+      .inject(BrowserHeadProvider)
+      .renderHead(
+        window.document,
+        typeof head === "function" ? head(current) : head || {},
+      );
+  }, []);
+
+  useEffect(() => {
+    if (options) {
+      setHead(options);
+    }
+  }, []);
+
+  return [current, setHead];
+};
+
+export type UseHeadOptions = Head | ((previous?: Head) => Head);
+
+export type UseHeadReturn = [
+  Head,
+  (head?: Head | ((previous?: Head) => Head)) => void,
+];