@jamx-framework/renderer 0.1.0

package/src/jsx/jsx-runtime.ts

@@ -0,0 +1,247 @@
+// ── TIPOS DEL ÁRBOL JSX ───────────────────────────────────────────────────
+
+export type JamxNode =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | JamxElement
+  | JamxNode[];
+
+export interface JamxElement {
+  type: string | ComponentFn;
+  props: Props;
+  key: string | null;
+}
+
+export type Props = Record<string, unknown> & {
+  children?: JamxNode | JamxNode[];
+};
+
+export type ComponentFn = (props: Props) => JamxNode;
+
+// ── JSX RUNTIME ───────────────────────────────────────────────────────────
+
+/**
+ * Función principal del JSX runtime.
+ * TypeScript llama esto cuando encuentra <Tag prop="value" />
+ *
+ * En lugar de React.createElement, JAMX usa esta función
+ * para construir el árbol de nodos que luego serializa a HTML.
+ */
+export function jsx(
+  type: string | ComponentFn,
+  props: Props,
+  key?: string,
+): JamxElement {
+  return {
+    type,
+    props: props ?? {},
+    key: key ?? null,
+  };
+}
+
+/**
+ * Versión para elementos con múltiples hijos.
+ * TypeScript la usa cuando hay más de un hijo.
+ */
+export const jsxs = jsx;
+
+/**
+ * Versión dev con información adicional para debugging.
+ * En producción es igual a jsx.
+ */
+export const jsxDEV = jsx;
+
+/**
+ * Fragment — permite retornar múltiples elementos sin wrapper.
+ * Uso: <> <div/> <div/> </>
+ */
+export const Fragment = "jamx.fragment" as const;
+
+// ── TIPOS GLOBALES JSX ────────────────────────────────────────────────────
+
+/**
+ * Declaraciones de tipos para que TypeScript entienda el JSX de JAMX.
+ * Estas interfaces definen qué props acepta cada elemento HTML.
+ */
+export namespace JSX {
+  export type Element = JamxElement;
+
+  export interface ElementChildrenAttribute {
+    children: JamxNode | JamxNode[];
+  }
+
+  export interface IntrinsicElements {
+    // Document
+    html: HtmlAttributes & { lang?: string };
+    head: HtmlAttributes;
+    body: HtmlAttributes;
+    title: HtmlAttributes;
+    meta: MetaAttributes;
+    link: LinkAttributes;
+    script: ScriptAttributes;
+    style: HtmlAttributes;
+    // Sections
+    main: HtmlAttributes;
+    header: HtmlAttributes;
+    footer: HtmlAttributes;
+    nav: HtmlAttributes;
+    section: HtmlAttributes;
+    article: HtmlAttributes;
+    aside: HtmlAttributes;
+    // Headings
+    h1: HtmlAttributes;
+    h2: HtmlAttributes;
+    h3: HtmlAttributes;
+    h4: HtmlAttributes;
+    h5: HtmlAttributes;
+    h6: HtmlAttributes;
+    // Text
+    p: HtmlAttributes;
+    span: HtmlAttributes;
+    strong: HtmlAttributes;
+    em: HtmlAttributes;
+    small: HtmlAttributes;
+    code: HtmlAttributes;
+    pre: HtmlAttributes;
+    // Lists
+    ul: HtmlAttributes;
+    ol: HtmlAttributes;
+    li: HtmlAttributes;
+    // Interactive
+    a: AnchorAttributes;
+    button: ButtonAttributes;
+    input: InputAttributes;
+    textarea: TextareaAttributes;
+    select: HtmlAttributes;
+    option: HtmlAttributes & { value?: string; selected?: boolean };
+    form: FormAttributes;
+    label: HtmlAttributes & { for?: string; htmlFor?: string };
+    // Media
+    img: ImgAttributes;
+    video: HtmlAttributes & {
+      src?: string;
+      controls?: boolean;
+      autoplay?: boolean;
+    };
+    audio: HtmlAttributes & { src?: string; controls?: boolean };
+    canvas: HtmlAttributes & { width?: number; height?: number };
+    // Layout
+    div: HtmlAttributes;
+    table: HtmlAttributes;
+    thead: HtmlAttributes;
+    tbody: HtmlAttributes;
+    tr: HtmlAttributes;
+    th: HtmlAttributes & { colSpan?: number; rowSpan?: number };
+    td: HtmlAttributes & { colSpan?: number; rowSpan?: number };
+    // Misc
+    br: HtmlAttributes;
+    hr: HtmlAttributes;
+    slot: HtmlAttributes & { name?: string };
+    // Generic fallback
+    [tag: string]: HtmlAttributes;
+  }
+}
+
+// ── TIPOS DE ATRIBUTOS ────────────────────────────────────────────────────
+
+export interface HtmlAttributes {
+  id?: string;
+  class?: string;
+  className?: string;
+  style?: string | Record<string, string>;
+  children?: JamxNode | JamxNode[];
+  // Data attributes
+  [key: `data-${string}`]: string | undefined;
+  // ARIA
+  role?: string;
+  "aria-label"?: string;
+  "aria-hidden"?: boolean;
+  "aria-expanded"?: boolean;
+  "aria-disabled"?: boolean;
+  "aria-selected"?: boolean;
+  "aria-controls"?: string;
+  "aria-describedby"?: string;
+  tabIndex?: number;
+}
+
+export interface AnchorAttributes extends HtmlAttributes {
+  href?: string;
+  target?: "_blank" | "_self" | "_parent" | "_top";
+  rel?: string;
+  download?: boolean | string;
+}
+
+export interface ButtonAttributes extends HtmlAttributes {
+  type?: "button" | "submit" | "reset";
+  disabled?: boolean;
+  name?: string;
+  value?: string;
+}
+
+export interface InputAttributes extends HtmlAttributes {
+  type?: string;
+  name?: string;
+  value?: string | number;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+  checked?: boolean;
+  min?: string | number;
+  max?: string | number;
+  step?: string | number;
+  pattern?: string;
+  autocomplete?: string;
+}
+
+export interface TextareaAttributes extends HtmlAttributes {
+  name?: string;
+  rows?: number;
+  cols?: number;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+}
+
+export interface FormAttributes extends HtmlAttributes {
+  action?: string;
+  method?: "get" | "post";
+  enctype?: string;
+}
+
+export interface ImgAttributes extends HtmlAttributes {
+  src?: string;
+  alt?: string;
+  width?: number | string;
+  height?: number | string;
+  loading?: "lazy" | "eager";
+}
+
+export interface MetaAttributes extends HtmlAttributes {
+  name?: string;
+  content?: string;
+  charset?: string;
+  httpEquiv?: string;
+  property?: string;
+  "http-equiv"?: string;
+}
+
+export interface LinkAttributes extends HtmlAttributes {
+  rel?: string;
+  href?: string;
+  type?: string;
+  media?: string;
+  as?: string;
+}
+
+export interface ScriptAttributes extends HtmlAttributes {
+  src?: string;
+  type?: string;
+  async?: boolean;
+  defer?: boolean;
+  module?: boolean;
+}

package/src/pipeline/context.ts

@@ -0,0 +1,45 @@
+/**
+ * Contexto disponible durante el render de una página.
+ * Se pasa al componente para que pueda acceder a datos
+ * de la request sin importar directamente @jamx-framework/server.
+ */
+export interface RenderContext {
+  /** Path de la ruta actual. Ej: /users/123 */
+  path: string;
+  /** Params de la ruta. Ej: { id: '123' } */
+  params: Record<string, string>;
+  /** Query string parseado */
+  query: Record<string, string | string[]>;
+  /** Headers de la request */
+  headers: Record<string, string | string[] | undefined>;
+  /** Entorno actual */
+  env: "development" | "production" | "test";
+}
+
+/**
+ * Resultado del render de una página.
+ */
+export interface RenderResult {
+  /** HTML completo listo para enviar */
+  html: string;
+  /** Status HTTP a usar en la response */
+  statusCode: number;
+  /** Headers adicionales para la response */
+  headers: Record<string, string>;
+}
+
+/**
+ * Metadatos de una página para el <head>.
+ */
+export interface PageHead {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  og?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    type?: string;
+  };
+  [key: string]: unknown;
+}

package/src/pipeline/renderer.ts

@@ -0,0 +1,138 @@
+import { HtmlSerializer } from "../html/serializer.js";
+import type { RenderContext, RenderResult, PageHead } from "./context.js";
+import type { JamxNode } from "../jsx/jsx-runtime.js";
+
+export interface PageComponentLike {
+  render: (ctx: RenderContext) => JamxNode;
+  meta?: (ctx: RenderContext) => PageHead;
+  layout?: LayoutComponentLike;
+}
+
+export interface LayoutComponentLike {
+  render: (props: { children: JamxNode; ctx: RenderContext }) => JamxNode;
+}
+
+/**
+ * Renderer SSR de JAMX.
+ *
+ * Convierte un componente de página en un string HTML completo,
+ * listo para ser enviado al cliente.
+ *
+ * Flujo:
+ * 1. Llamar page.meta() para obtener los metadatos del <head>
+ * 2. Llamar page.render() para obtener el árbol JSX del contenido
+ * 3. Si hay layout, envolver el contenido en él
+ * 4. Serializar el árbol completo a HTML string
+ * 5. Envolver en el documento HTML base
+ */
+export class SSRRenderer {
+  private readonly serializer: HtmlSerializer;
+
+  constructor() {
+    this.serializer = new HtmlSerializer();
+  }
+
+  /**
+   * Renderiza una página completa a HTML.
+   */
+  async render(
+    page: PageComponentLike,
+    ctx: RenderContext,
+  ): Promise<RenderResult> {
+    // 1. Obtener metadatos
+    const head = page.meta?.(ctx) ?? {};
+
+    // 2. Renderizar el contenido de la página
+    const contentNode = page.render(ctx);
+
+    // 3. Aplicar layout si existe
+    const bodyNode = page.layout
+      ? page.layout.render({ children: contentNode, ctx })
+      : contentNode;
+
+    // 4. Serializar a string
+    const bodyHtml = this.serializer.serialize(bodyNode);
+
+    // 5. Construir el documento HTML completo
+    const html = this.buildDocument(bodyHtml, head, ctx);
+
+    return {
+      html,
+      statusCode: 200,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+      },
+    };
+  }
+
+  /**
+   * Construye el documento HTML completo con el <head> y el <body>.
+   */
+  private buildDocument(
+    bodyHtml: string,
+    head: PageHead,
+    ctx: RenderContext,
+  ): string {
+    const title = head.title ?? "JAMX App";
+    const description = head.description ?? "";
+    const isDev = ctx.env === "development";
+
+    const metaTags = this.buildMetaTags(head);
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeTitle(title)}</title>
+  ${description ? `<meta name="description" content="${escapeAttr(description)}" />` : ""}
+  ${metaTags}
+  <link rel="stylesheet" href="/__jamx/styles.css" />
+</head>
+<body>
+  <div id="__jamx_root__" data-route="${escapeAttr(ctx.path)}">${bodyHtml}</div>
+  <script type="module" src="/__jamx/client.js"${isDev ? ' data-dev="true"' : ""}></script>
+</body>
+</html>`;
+  }
+
+  private buildMetaTags(head: PageHead): string {
+    const tags: string[] = [];
+
+    if (head.og) {
+      const og = head.og;
+      if (og.title)
+        tags.push(
+          `<meta property="og:title" content="${escapeAttr(og.title)}" />`,
+        );
+      if (og.description)
+        tags.push(
+          `<meta property="og:description" content="${escapeAttr(og.description)}" />`,
+        );
+      if (og.image)
+        tags.push(
+          `<meta property="og:image" content="${escapeAttr(og.image)}" />`,
+        );
+      if (og.type)
+        tags.push(
+          `<meta property="og:type" content="${escapeAttr(og.type)}" />`,
+        );
+    }
+
+    return tags.join("\n  ");
+  }
+}
+
+// ── HELPERS ───────────────────────────────────────────────────────────────
+
+function escapeTitle(str: string): string {
+  return str.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeAttr(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/test/unit/error/boundary.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { ErrorBoundary } from "../../../src/error/boundary.js";
+import { HttpException } from "@jamx-framework/core";
+
+describe("ErrorBoundary", () => {
+  it("retorna caught: false si no hay error", async () => {
+    const result = await ErrorBoundary.wrap(async () => "hello", {
+      isDev: false,
+    });
+    expect(result.caught).toBe(false);
+    if (!result.caught) expect(result.value).toBe("hello");
+  });
+
+  it("retorna caught: true con HTML si hay error", async () => {
+    const result = await ErrorBoundary.wrap(
+      async () => {
+        throw new Error("Something broke");
+      },
+      { isDev: false },
+    );
+    expect(result.caught).toBe(true);
+    if (result.caught) {
+      expect(result.statusCode).toBe(500);
+      expect(result.html).toContain("500");
+    }
+  });
+
+  it("usa el statusCode de HttpException", async () => {
+    const result = await ErrorBoundary.wrap(
+      async () => {
+        throw new HttpException(
+          404,
+          "Not Found",
+          "Page not found",
+          "NOT_FOUND",
+        );
+      },
+      { isDev: false },
+    );
+    expect(result.caught).toBe(true);
+    if (result.caught) expect(result.statusCode).toBe(404);
+  });
+
+  it("incluye stack trace en dev", async () => {
+    const result = await ErrorBoundary.wrap(
+      async () => {
+        throw new Error("Dev error");
+      },
+      { isDev: true },
+    );
+    expect(result.caught).toBe(true);
+    if (result.caught) {
+      expect(result.html).toContain("Dev error");
+    }
+  });
+
+  it("toRenderError convierte Error genérico a statusCode 500", () => {
+    const error = ErrorBoundary.toRenderError(new Error("boom"));
+    expect(error.statusCode).toBe(500);
+    expect(error.message).toBe("boom");
+  });
+
+  it("toRenderError maneja valores no-Error", () => {
+    const error = ErrorBoundary.toRenderError("string error");
+    expect(error.statusCode).toBe(500);
+  });
+
+  it("incluye el path en el error", async () => {
+    const result = await ErrorBoundary.wrap(
+      async () => {
+        throw new Error("Page error");
+      },
+      { isDev: false, path: "/about" },
+    );
+    expect(result.caught).toBe(true);
+    if (result.caught) expect(result.error.path).toBe("/about");
+  });
+});

package/test/unit/error/error-page.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { renderErrorPage } from "../../../src/error/error-page.js";
+
+describe("renderErrorPage", () => {
+  it("incluye el status code en el HTML", () => {
+    const html = renderErrorPage(
+      { statusCode: 404, message: "Not Found" },
+      false,
+    );
+    expect(html).toContain("404");
+    expect(html).toContain("Not Found");
+  });
+
+  it("incluye el mensaje de error", () => {
+    const html = renderErrorPage(
+      { statusCode: 500, message: "Something went wrong" },
+      false,
+    );
+    expect(html).toContain("Something went wrong");
+  });
+
+  it("en dev muestra el stack trace", () => {
+    const html = renderErrorPage(
+      {
+        statusCode: 500,
+        message: "Error",
+        stack: "Error: test\n  at foo.ts:1:1",
+      },
+      true,
+    );
+    expect(html).toContain("at foo.ts:1:1");
+  });
+
+  it("en producción NO muestra el stack trace", () => {
+    const html = renderErrorPage(
+      {
+        statusCode: 500,
+        message: "Error",
+        stack: "Error: secret stack",
+      },
+      false,
+    );
+    expect(html).not.toContain("secret stack");
+  });
+
+  it("escapa HTML en el mensaje", () => {
+    const html = renderErrorPage(
+      { statusCode: 400, message: '<script>alert("xss")</script>' },
+      false,
+    );
+    expect(html).not.toContain("<script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  it("genera HTML válido con DOCTYPE", () => {
+    const html = renderErrorPage(
+      { statusCode: 404, message: "Not Found" },
+      false,
+    );
+    expect(html).toMatch(/^<!DOCTYPE html>/);
+    expect(html).toContain("</html>");
+  });
+});

package/test/unit/html/escape.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { escapeHtml } from "../../../src/html/escape.js";
+
+describe("escapeHtml", () => {
+  it("escapa &", () => {
+    expect(escapeHtml("a & b")).toBe("a & b");
+  });
+
+  it("escapa <", () => {
+    expect(escapeHtml("<div>")).toBe("&lt;div&gt;");
+  });
+
+  it('escapa "', () => {
+    expect(escapeHtml('"quoted"')).toBe("&quot;quoted&quot;");
+  });
+
+  it("escapa '", () => {
+    expect(escapeHtml("it's")).toBe("it&#39;s");
+  });
+
+  it("escapa múltiples caracteres", () => {
+    expect(escapeHtml('<script>alert("xss")</script>')).toBe(
+      "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;",
+    );
+  });
+
+  it("no modifica texto sin caracteres especiales", () => {
+    expect(escapeHtml("hello world")).toBe("hello world");
+  });
+
+  it("convierte números a string", () => {
+    expect(escapeHtml(42)).toBe("42");
+  });
+});

package/test/unit/html/renderer.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { SSRRenderer } from "../../../src/pipeline/renderer.js";
+import { jsx } from "../../../src/jsx/jsx-runtime.js";
+import type { RenderContext } from "../../../src/pipeline/context.js";
+
+const renderer = new SSRRenderer();
+
+const ctx: RenderContext = {
+  path: "/test",
+  params: {},
+  query: {},
+  headers: {},
+  env: "test",
+};
+
+describe("SSRRenderer", () => {
+  it("renderiza una página simple a HTML", async () => {
+    const page = {
+      render: () => jsx("h1", { children: "Hello World" }),
+    };
+
+    const result = await renderer.render(page, ctx);
+
+    expect(result.statusCode).toBe(200);
+    expect(result.html).toContain("<!DOCTYPE html>");
+    expect(result.html).toContain("<h1>Hello World</h1>");
+  });
+
+  it("incluye el title de los metadatos", async () => {
+    const page = {
+      render: () => jsx("div", { children: "content" }),
+      meta: () => ({ title: "My Page Title" }),
+    };
+
+    const result = await renderer.render(page, ctx);
+    expect(result.html).toContain("<title>My Page Title</title>");
+  });
+
+  it("incluye la meta description", async () => {
+    const page = {
+      render: () => jsx("div", {}),
+      meta: () => ({ description: "Page description here" }),
+    };
+
+    const result = await renderer.render(page, ctx);
+    expect(result.html).toContain("Page description here");
+  });
+
+  it("incluye el __jamx_root__ con data-route", async () => {
+    const page = {
+      render: () => jsx("span", { children: "content" }),
+    };
+
+    const result = await renderer.render(page, {
+      ...ctx,
+      path: "/users/123",
+    });
+
+    expect(result.html).toContain('id="__jamx_root__"');
+    expect(result.html).toContain('data-route="/users/123"');
+  });
+
+  it("aplica el layout si está definido", async () => {
+    const page = {
+      render: () => jsx("main", { children: "Page content" }),
+      layout: {
+        render: ({ children }: { children: unknown }) =>
+          jsx("div", { className: "layout", children: children as never }),
+      },
+    };
+
+    const result = await renderer.render(page, ctx);
+    expect(result.html).toContain('<div class="layout">');
+    expect(result.html).toContain("<main>Page content</main>");
+  });
+
+  it("escapa el title para prevenir XSS", async () => {
+    const page = {
+      render: () => jsx("div", {}),
+      meta: () => ({ title: '<script>alert("xss")</script>' }),
+    };
+
+    const result = await renderer.render(page, ctx);
+    expect(result.html).not.toContain("<script>alert");
+    expect(result.html).toContain("&lt;script&gt;");
+  });
+
+  it("retorna Content-Type correcto en headers", async () => {
+    const page = { render: () => jsx("div", {}) };
+    const result = await renderer.render(page, ctx);
+    expect(result.headers["Content-Type"]).toBe("text/html; charset=utf-8");
+  });
+});