alepha 0.15.1 → 0.15.3

package/src/react/head/index.browser.ts

@@ -0,0 +1,26 @@
+import { $module } from "alepha";
+import { AlephaReact } from "alepha/react";
+import { $head } from "./primitives/$head.ts";
+import { BrowserHeadProvider } from "./providers/BrowserHeadProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./helpers/SeoExpander.ts";
+export * from "./hooks/useHead.ts";
+export * from "./interfaces/Head.ts";
+export * from "./primitives/$head.ts";
+export * from "./providers/BrowserHeadProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Alepha React Head Module
+ *
+ * @see {@link BrowserHeadProvider}
+ * @module alepha.react.head
+ */
+export const AlephaReactHead = $module({
+  name: "alepha.react.head",
+  primitives: [$head],
+  services: [AlephaReact, BrowserHeadProvider],
+});

package/src/react/head/index.ts

@@ -0,0 +1,44 @@
+import { $module } from "alepha";
+import { AlephaReact } from "alepha/react";
+import { SeoExpander } from "./helpers/SeoExpander.ts";
+import { $head } from "./primitives/$head.ts";
+import { BrowserHeadProvider } from "./providers/BrowserHeadProvider.ts";
+import { HeadProvider } from "./providers/HeadProvider.ts";
+import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./helpers/SeoExpander.ts";
+export * from "./hooks/useHead.ts";
+export * from "./interfaces/Head.ts";
+export * from "./primitives/$head.ts";
+export * from "./providers/BrowserHeadProvider.ts";
+export * from "./providers/ServerHeadProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | standard | stable |
+ *
+ * HTML head element management.
+ *
+ * **Features:**
+ * - Title, meta tags, and links
+ * - SEO optimization
+ * - Social media tags
+ *
+ * @module alepha.react.head
+ */
+export const AlephaReactHead = $module({
+  name: "alepha.react.head",
+  primitives: [$head],
+  services: [
+    AlephaReact,
+    BrowserHeadProvider,
+    HeadProvider,
+    SeoExpander,
+    ServerHeadProvider,
+  ],
+});

package/src/react/head/interfaces/Head.ts

@@ -0,0 +1,105 @@
+/**
+ * Complete head configuration combining basic head elements with SEO fields.
+ *
+ * @example
+ * ```ts
+ * $head({
+ *   title: "My App",
+ *   description: "Build amazing apps",
+ *   image: "https://example.com/og.png",
+ *   url: "https://example.com/",
+ *   siteName: "My App",
+ *   twitter: { card: "summary_large_image" },
+ * })
+ * ```
+ */
+export interface Head extends SimpleHead, Seo {}
+
+/**
+ * SEO configuration for automatic meta tag generation.
+ * Fields are used for meta description, OpenGraph, and Twitter Card tags.
+ */
+export interface Seo {
+  /** Page description - used for meta description, og:description, twitter:description */
+  description?: string;
+  /** Primary image URL - used for og:image and twitter:image */
+  image?: string;
+  /** Canonical URL - used for og:url and link rel="canonical" */
+  url?: string;
+  /** Site name - used for og:site_name */
+  siteName?: string;
+  /** Locale - used for og:locale (e.g., "en_US") */
+  locale?: string;
+  /** Content type - used for og:type (default: "website") */
+  type?: "website" | "article" | "product" | "profile" | string;
+  /** Image width in pixels - used for og:image:width */
+  imageWidth?: number;
+  /** Image height in pixels - used for og:image:height */
+  imageHeight?: number;
+  /** Image alt text - used for og:image:alt and twitter:image:alt */
+  imageAlt?: string;
+
+  /** Twitter-specific overrides */
+  twitter?: {
+    /** Twitter card type */
+    card?: "summary" | "summary_large_image" | "app" | "player";
+    /** @username of website */
+    site?: string;
+    /** @username of content creator */
+    creator?: string;
+    /** Override title for Twitter */
+    title?: string;
+    /** Override description for Twitter */
+    description?: string;
+    /** Override image for Twitter */
+    image?: string;
+  };
+
+  /** OpenGraph-specific overrides */
+  og?: {
+    /** Override title for OpenGraph */
+    title?: string;
+    /** Override description for OpenGraph */
+    description?: string;
+    /** Override image for OpenGraph */
+    image?: string;
+  };
+}
+
+export interface SimpleHead {
+  title?: string;
+  titleSeparator?: string;
+  /** Document charset - defaults to "UTF-8" if not specified */
+  charset?: string;
+  /** Viewport content - defaults to "width=device-width, initial-scale=1" if not specified */
+  viewport?: string;
+  htmlAttributes?: Record<string, string>;
+  bodyAttributes?: Record<string, string>;
+  /** Meta tags - supports both name and property attributes */
+  meta?: Array<HeadMeta>;
+  /** Link tags (e.g., stylesheets, preload, canonical) */
+  link?: Array<{
+    rel: string;
+    href: string;
+    type?: string;
+    as?: string;
+    crossorigin?: string;
+  }>;
+  /** Script tags - string for inline code, or object with attributes */
+  script?: Array<
+    | string
+    | (Record<string, string | boolean | undefined> & {
+        /** Inline JavaScript code */
+        content?: string;
+      })
+  >;
+}
+
+export interface HeadMeta {
+  /** Meta name attribute (e.g., "description", "twitter:card") */
+  name?: string;
+  /** Meta property attribute (e.g., "og:title", "og:image") */
+  property?: string;
+  /** Meta content value */
+  content: string;
+}

package/src/react/head/primitives/$head.ts

@@ -0,0 +1,25 @@
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
+import type { Head } from "../interfaces/Head.ts";
+import { HeadProvider } from "../providers/HeadProvider.ts";
+
+/**
+ * Set global `<head>` options for the application.
+ */
+export const $head = (options: HeadPrimitiveOptions) => {
+  return createPrimitive(HeadPrimitive, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export type HeadPrimitiveOptions = Head | (() => Head);
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class HeadPrimitive extends Primitive<HeadPrimitiveOptions> {
+  protected readonly provider = $inject(HeadProvider);
+  protected onInit() {
+    this.provider.global = [...(this.provider.global ?? []), this.options];
+  }
+}
+
+$head[KIND] = HeadPrimitive;

package/src/react/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/react/head/providers/BrowserHeadProvider.ts

@@ -0,0 +1,212 @@
+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;
+  }
+
+  /**
+   * 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;
+    }
+
+    this.headProvider.fillHead(state as any);
+    if (state.head) {
+      this.renderHead(this.document, state.head);
+    }
+  }
+
+  public getHead(document: Document): Head {
+    return {
+      get title() {
+        return document.title;
+      },
+      get htmlAttributes() {
+        const attrs: Record<string, string> = {};
+        for (const attr of document.documentElement.attributes) {
+          attrs[attr.name] = attr.value;
+        }
+        return attrs;
+      },
+      get bodyAttributes() {
+        const attrs: Record<string, string> = {};
+        for (const attr of document.body.attributes) {
+          attrs[attr.name] = attr.value;
+        }
+        return attrs;
+      },
+      get meta() {
+        const metas: HeadMeta[] = [];
+        // Get meta tags with name attribute
+        for (const meta of document.head.querySelectorAll("meta[name]")) {
+          const name = meta.getAttribute("name");
+          const content = meta.getAttribute("content");
+          if (name && content) {
+            metas.push({ name, content });
+          }
+        }
+        // Get meta tags with property attribute (OpenGraph)
+        for (const meta of document.head.querySelectorAll("meta[property]")) {
+          const property = meta.getAttribute("property");
+          const content = meta.getAttribute("content");
+          if (property && content) {
+            metas.push({ property, content });
+          }
+        }
+        return metas;
+      },
+    };
+  }
+
+  public renderHead(document: Document, head: Head): void {
+    if (head.title) {
+      document.title = head.title;
+    }
+
+    if (head.bodyAttributes) {
+      for (const [key, value] of Object.entries(head.bodyAttributes)) {
+        if (value) {
+          document.body.setAttribute(key, value);
+        } else {
+          document.body.removeAttribute(key);
+        }
+      }
+    }
+
+    if (head.htmlAttributes) {
+      for (const [key, value] of Object.entries(head.htmlAttributes)) {
+        if (value) {
+          document.documentElement.setAttribute(key, value);
+        } else {
+          document.documentElement.removeAttribute(key);
+        }
+      }
+    }
+
+    if (head.meta) {
+      for (const it of head.meta) {
+        this.renderMetaTag(document, it);
+      }
+    }
+
+    if (head.link) {
+      for (const it of head.link) {
+        const { rel, href } = it;
+        let link = document.querySelector(`link[rel="${rel}"][href="${href}"]`);
+        if (!link) {
+          link = document.createElement("link");
+          link.setAttribute("rel", rel);
+          link.setAttribute("href", href);
+          if (it.type) {
+            link.setAttribute("type", it.type);
+          }
+          if (it.as) {
+            link.setAttribute("as", it.as);
+          }
+          if (it.crossorigin != null) {
+            link.setAttribute("crossorigin", "");
+          }
+          document.head.appendChild(link);
+        }
+      }
+    }
+
+    if (head.script) {
+      for (const it of head.script) {
+        this.renderScriptTag(document, it);
+      }
+    }
+  }
+
+  protected renderScriptTag(
+    document: Document,
+    script:
+      | string
+      | (Record<string, string | boolean | undefined> & { content?: string }),
+  ): void {
+    const el = document.createElement("script");
+
+    // Handle plain string as inline script
+    if (typeof script === "string") {
+      el.textContent = script;
+      document.head.appendChild(el);
+      return;
+    }
+
+    const { content, ...attrs } = script;
+
+    // For scripts with src, check if already exists
+    if (attrs.src) {
+      const existing = document.querySelector(`script[src="${attrs.src}"]`);
+      if (existing) {
+        return;
+      }
+    }
+
+    for (const [key, value] of Object.entries(attrs)) {
+      if (value === true) {
+        el.setAttribute(key, "");
+      } else if (value !== undefined && value !== false) {
+        el.setAttribute(key, String(value));
+      }
+    }
+
+    if (content) {
+      el.textContent = content;
+    }
+
+    document.head.appendChild(el);
+  }
+
+  protected renderMetaTag(document: Document, meta: HeadMeta): void {
+    const { content } = meta;
+
+    // Handle OpenGraph tags (property attribute)
+    if (meta.property) {
+      const existing = document.querySelector(
+        `meta[property="${meta.property}"]`,
+      );
+      if (existing) {
+        existing.setAttribute("content", content);
+      } else {
+        const newMeta = document.createElement("meta");
+        newMeta.setAttribute("property", meta.property);
+        newMeta.setAttribute("content", content);
+        document.head.appendChild(newMeta);
+      }
+      return;
+    }
+
+    // Handle standard meta tags (name attribute)
+    if (meta.name) {
+      const existing = document.querySelector(`meta[name="${meta.name}"]`);
+      if (existing) {
+        existing.setAttribute("content", content);
+      } else {
+        const newMeta = document.createElement("meta");
+        newMeta.setAttribute("name", meta.name);
+        newMeta.setAttribute("content", content);
+        document.head.appendChild(newMeta);
+      }
+    }
+  }
+}