@alepha/react 0.14.0 → 0.14.2

package/src/head/helpers/SeoExpander.ts

@@ -0,0 +1,141 @@
+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/head/index.browser.ts

@@ -8,6 +8,7 @@ import { BrowserHeadProvider } from "./providers/BrowserHeadProvider.ts";
 export * from "./primitives/$head.ts";
 export * from "./hooks/useHead.ts";
 export * from "./interfaces/Head.ts";
+export * from "./helpers/SeoExpander.ts";
 export * from "./providers/BrowserHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/head/index.ts

@@ -1,9 +1,9 @@
-import {
-  AlephaReact,
-  type PageConfigSchema,
-  type TPropsDefault,
-  type TPropsParentDefault,
-} from "@alepha/react";
+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";
@@ -15,11 +15,13 @@ import { HeadProvider } from "./providers/HeadProvider.ts";
 export * from "./primitives/$head.ts";
 export * from "./hooks/useHead.ts";
 export * from "./interfaces/Head.ts";
+export * from "./helpers/SeoExpander.ts";
 export * from "./providers/ServerHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-declare module "@alepha/react" {
+// Augment PagePrimitiveOptions in router module
+declare module "@alepha/react/router" {
   interface PagePrimitiveOptions<
     TConfig extends PageConfigSchema = PageConfigSchema,
     TProps extends object = TPropsDefault,
@@ -27,7 +29,10 @@ declare module "@alepha/react" {
   > {
     head?: Head | ((props: TProps, previous?: Head) => Head);
   }
+}
 
+// Augment ReactRouterState in router module
+declare module "@alepha/react/router" {
   interface ReactRouterState {
     head: Head;
   }
@@ -38,6 +43,11 @@ declare module "@alepha/react" {
 /**
  * Fill `<head>` server & client side.
  *
+ * Generate SEO-friendly meta tags and titles for your React application using AlephaReactHead module.
+ *
+ * This module provides services and primitives to manage the document head both on the server and client side,
+ * ensuring that your application is optimized for search engines and social media sharing.
+ *
  * @see {@link ServerHeadProvider}
  * @module alepha.react.head
  */

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,19 @@ 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 tags (e.g., stylesheets, preload, canonical) */
   link?: Array<{ rel: string; href: string }>;
+  /** Script tags - any valid script attributes (src, type, async, defer, etc.) */
+  script?: Array<Record<string, string | boolean>>;
+}
+
+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 type { PageRoute, ReactRouterState } from "@alepha/react/router";
+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,18 @@ 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 ?? [])],
+      script: [...(state.head.script ?? []), ...(head.script ?? [])],
+    };
+  }
+
   protected fillHeadByPage(
     page: PageRoute,
     state: ReactRouterState,
@@ -42,6 +53,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 +87,13 @@ 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 ?? [])];
+    }
+
+    if (head.script) {
+      state.head.script = [...(state.head.script ?? []), ...(head.script ?? [])];
+    }
   }
 }

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);
       }
     }
 
@@ -68,6 +68,12 @@ export class ServerHeadProvider {
       }
     }
 
+    if (head.script) {
+      for (const script of head.script) {
+        headContent += this.renderScriptTag(script);
+      }
+    }
+
     // Inject into <head>...</head>
     result = result.replace(
       /<head([^>]*)>(.*?)<\/head>/is,
@@ -112,4 +118,30 @@ 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 "";
+  }
+
+  protected renderScriptTag(script: Record<string, string | boolean>): string {
+    const attrs = Object.entries(script)
+      .filter(([, value]) => value !== false)
+      .map(([key, value]) => {
+        // Boolean attributes - render without value if true
+        if (value === true) {
+          return key;
+        }
+        return `${key}="${this.escapeHtml(String(value))}"`;
+      })
+      .join(" ");
+    return `<script ${attrs}></script>\n`;
+  }
 }

package/src/{core → router}/components/ErrorViewer.tsx

@@ -47,6 +47,8 @@ const ErrorViewer = ({ error, alepha }: ErrorViewerProps) => {
 
 export default ErrorViewer;
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * Parse stack trace string into structured frames
  */

package/src/router/components/Link.tsx

@@ -0,0 +1,21 @@
+import { type AnchorHTMLAttributes, createElement } from "react";
+import { useRouter } from "../hooks/useRouter.ts";
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+}
+
+/**
+ * Link component for client-side navigation.
+ *
+ * It's a simple wrapper around an anchor (`<a>`) element using the `useRouter` hook.
+ */
+const Link = (props: LinkProps) => {
+  const router = useRouter();
+
+  return createElement(
+    "a", { ...props, ...router.anchor(props.href) }, props.children
+  )
+};
+
+export default Link;

package/src/{core → router}/components/NestedView.tsx

@@ -1,13 +1,11 @@
 import { memo, type ReactNode, use, useRef, useState } from "react";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { ErrorHandler, PageAnimation } from "../primitives/$page.ts";
 import { Redirection } from "../errors/Redirection.ts";
-import { useEvents } from "../hooks/useEvents.ts";
 import { useRouterState } from "../hooks/useRouterState.ts";
-import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
-import ErrorBoundary from "./ErrorBoundary.tsx";
+import type { PageAnimation } from "../primitives/$page.ts";
 import ErrorViewer from "./ErrorViewer.tsx";
-import { useAlepha } from "../hooks/useAlepha.ts";
+import { ErrorBoundary, useAlepha, useEvents } from "@alepha/react";
 
 export interface NestedViewProps {
   children?: ReactNode;

package/src/router/components/NotFound.tsx

@@ -0,0 +1,30 @@
+import type { CSSProperties } from "react";
+
+/**
+ * Default 404 Not Found page component.
+ */
+ const NotFound = (props: { style?: CSSProperties }) => (
+  <div
+    style={{
+      width: "100%",
+      minHeight: "90vh",
+      boxSizing: "border-box",
+      display: "flex",
+      flexDirection: "column",
+      justifyContent: "center",
+      alignItems: "center",
+      textAlign: "center",
+      fontFamily:
+        'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      padding: "2rem",
+      ...props.style,
+    }}
+  >
+    <div style={{ fontSize: "6rem", fontWeight: 200, lineHeight: 1 }}>404</div>
+    <div style={{ fontSize: "0.875rem", marginTop: "1rem", opacity: 0.6 }}>
+      Page not found
+    </div>
+  </div>
+)
+
+export default NotFound;

package/src/router/errors/Redirection.ts

@@ -0,0 +1,28 @@
+import { AlephaError } from "alepha";
+
+/**
+ * Used for Redirection during the page loading.
+ *
+ * Depends on the context, it can be thrown or just returned.
+ *
+ * @example
+ * ```ts
+ * import { Redirection } from "@alepha/react";
+ *
+ * const MyPage = $page({
+ *   resolve: async () => {
+ *    if (needRedirect) {
+ *      throw new Redirection("/new-path");
+ *    }
+ *   },
+ * });
+ * ```
+ */
+export class Redirection extends AlephaError {
+  public readonly redirect: string;
+
+  constructor(redirect: string) {
+    super("Redirection");
+    this.redirect = redirect;
+  }
+}

package/src/{core → router}/hooks/useActive.ts

@@ -8,11 +8,15 @@ export interface UseActiveOptions {
   startWith?: boolean;
 }
 
+/**
+ * Hook to determine if a given route is active and to provide anchor props for navigation.
+ * This hook refreshes on router state changes.
+ */
 export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
+  useRouterState();
+
   const router = useRouter();
   const [isPending, setPending] = useState(false);
-  const state = useRouterState();
-  const current = state.url.pathname;
 
   const options: UseActiveOptions =
     typeof args === "string" ? { href: args } : { ...args, href: args.href };

package/src/{core → router}/hooks/useQueryParams.ts

@@ -1,10 +1,10 @@
 import type { Alepha, Static, TObject } from "alepha";
 import { useEffect, useState } from "react";
-import { useAlepha } from "./useAlepha.ts";
+import { useAlepha } from "@alepha/react";
 import { useRouter } from "./useRouter.ts";
 
 /**
- * Not well tested. Use with caution.
+ * Hook to manage query parameters in the URL using a defined schema.
  */
 export const useQueryParams = <T extends TObject>(
   schema: T,