@alepha/react 0.14.0 → 0.14.1

package/src/head/interfaces/Head.ts

@@ -1,39 +1,68 @@
-export interface Head extends SimpleHead {
-  description?: string;
+/**
+ * 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 {}
 
-  // TODO
-  keywords?: string[];
-  author?: string;
-  robots?: string;
-  themeColor?: string;
-  viewport?:
-    | string
-    | {
-        width?: string;
-        height?: string;
-        initialScale?: string;
-        maximumScale?: string;
-        userScalable?: "no" | "yes" | "0" | "1";
-        interactiveWidget?:
-          | "resizes-visual"
-          | "resizes-content"
-          | "overlays-content";
-      };
+/**
+ * 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;
 
-  og?: {
+  /** 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;
-    url?: string;
-    type?: string;
   };
 
-  twitter?: {
-    card?: string;
+  /** OpenGraph-specific overrides */
+  og?: {
+    /** Override title for OpenGraph */
     title?: string;
+    /** Override description for OpenGraph */
     description?: string;
+    /** Override image for OpenGraph */
     image?: string;
-    site?: string;
   };
 }
 
@@ -42,6 +71,16 @@ export interface SimpleHead {
   titleSeparator?: string;
   htmlAttributes?: Record<string, string>;
   bodyAttributes?: Record<string, string>;
-  meta?: Array<{ name: string; content: string }>;
+  /** Meta tags - supports both name and property attributes */
+  meta?: Array<HeadMeta>;
   link?: Array<{ rel: string; href: 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/head/providers/BrowserHeadProvider.ts

@@ -1,5 +1,5 @@
 import { $hook, $inject } from "alepha";
-import type { Head } from "../interfaces/Head.ts";
+import type { Head, HeadMeta } from "../interfaces/Head.ts";
 import { HeadProvider } from "./HeadProvider.ts";
 
 export class BrowserHeadProvider {
@@ -49,7 +49,8 @@ export class BrowserHeadProvider {
         return attrs;
       },
       get meta() {
-        const metas: { name: string; content: string }[] = [];
+        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");
@@ -57,6 +58,14 @@ export class BrowserHeadProvider {
             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;
       },
     };
@@ -89,16 +98,7 @@ export class BrowserHeadProvider {
 
     if (head.meta) {
       for (const it of head.meta) {
-        const { name, content } = it;
-        const meta = document.querySelector(`meta[name="${name}"]`);
-        if (meta) {
-          meta.setAttribute("content", content);
-        } else {
-          const newMeta = document.createElement("meta");
-          newMeta.setAttribute("name", name);
-          newMeta.setAttribute("content", content);
-          document.head.appendChild(newMeta);
-        }
+        this.renderMetaTag(document, it);
       }
     }
 
@@ -115,4 +115,37 @@ export class BrowserHeadProvider {
       }
     }
   }
+
+  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);
+      }
+    }
+  }
 }

package/src/head/providers/HeadProvider.ts

@@ -1,7 +1,11 @@
 import type { PageRoute, ReactRouterState } from "@alepha/react";
+import { $inject } from "alepha";
+import { SeoExpander } from "../helpers/SeoExpander.ts";
 import type { Head } from "../interfaces/Head.ts";
 
 export class HeadProvider {
+  protected readonly seoExpander = $inject(SeoExpander);
+
   public global?: Array<Head | (() => Head)> = [];
 
   public fillHead(state: ReactRouterState) {
@@ -10,13 +14,8 @@ export class HeadProvider {
     };
 
     for (const h of this.global ?? []) {
-      const head =
-        typeof h === "function" ? h() : h;
-      state.head = {
-        ...state.head,
-        ...head,
-        meta: [...(state.head.meta ?? []), ...(head.meta ?? [])],
-      };
+      const head = typeof h === "function" ? h() : h;
+      this.mergeHead(state, head);
     }
 
     for (const layer of state.layers) {
@@ -26,6 +25,17 @@ export class HeadProvider {
     }
   }
 
+  protected mergeHead(state: ReactRouterState, head: Head): void {
+    // Expand SEO fields into meta tags
+    const { meta, link } = this.seoExpander.expand(head);
+    state.head = {
+      ...state.head,
+      ...head,
+      meta: [...(state.head.meta ?? []), ...meta, ...(head.meta ?? [])],
+      link: [...(state.head.link ?? []), ...link, ...(head.link ?? [])],
+    };
+  }
+
   protected fillHeadByPage(
     page: PageRoute,
     state: ReactRouterState,
@@ -42,6 +52,11 @@ export class HeadProvider {
         ? page.head(props, state.head)
         : page.head;
 
+    // Expand SEO fields into meta tags
+    const { meta, link } = this.seoExpander.expand(head);
+    state.head.meta = [...(state.head.meta ?? []), ...meta];
+    state.head.link = [...(state.head.link ?? []), ...link];
+
     if (head.title) {
       state.head ??= {};
 
@@ -71,5 +86,9 @@ export class HeadProvider {
     if (head.meta) {
       state.head.meta = [...(state.head.meta ?? []), ...(head.meta ?? [])];
     }
+
+    if (head.link) {
+      state.head.link = [...(state.head.link ?? []), ...(head.link ?? [])];
+    }
   }
 }

package/src/head/providers/ServerHeadProvider.ts

@@ -1,6 +1,6 @@
 import { $hook, $inject } from "alepha";
 import { ServerTimingProvider } from "alepha/server";
-import type { SimpleHead } from "../interfaces/Head.ts";
+import type { HeadMeta, SimpleHead } from "../interfaces/Head.ts";
 import { HeadProvider } from "./HeadProvider.ts";
 
 export class ServerHeadProvider {
@@ -58,7 +58,7 @@ export class ServerHeadProvider {
 
     if (head.meta) {
       for (const meta of head.meta) {
-        headContent += `<meta name="${this.escapeHtml(meta.name)}" content="${this.escapeHtml(meta.content)}">\n`;
+        headContent += this.renderMetaTag(meta);
       }
     }
 
@@ -112,4 +112,16 @@ export class ServerHeadProvider {
       .replace(/"/g, "&quot;")
       .replace(/'/g, "&#039;");
   }
+
+  protected renderMetaTag(meta: HeadMeta): string {
+    // OpenGraph tags use property attribute
+    if (meta.property) {
+      return `<meta property="${this.escapeHtml(meta.property)}" content="${this.escapeHtml(meta.content)}">\n`;
+    }
+    // Standard meta tags use name attribute
+    if (meta.name) {
+      return `<meta name="${this.escapeHtml(meta.name)}" content="${this.escapeHtml(meta.content)}">\n`;
+    }
+    return "";
+  }
 }