npm - @jamx-framework/renderer - Versions diffs - 0.1.0 - Mend

@jamx-framework/renderer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/.turbo/turbo-build.log +4 -0
package/dist/.tsbuildinfo +1 -0
package/dist/error/boundary.d.ts +36 -0
package/dist/error/boundary.d.ts.map +1 -0
package/dist/error/boundary.js +60 -0
package/dist/error/boundary.js.map +1 -0
package/dist/error/error-page.d.ts +7 -0
package/dist/error/error-page.d.ts.map +1 -0
package/dist/error/error-page.js +132 -0
package/dist/error/error-page.js.map +1 -0
package/dist/error/types.d.ts +7 -0
package/dist/error/types.d.ts.map +1 -0
package/dist/error/types.js +2 -0
package/dist/error/types.js.map +1 -0
package/dist/html/escape.d.ts +19 -0
package/dist/html/escape.d.ts.map +1 -0
package/dist/html/escape.js +85 -0
package/dist/html/escape.js.map +1 -0
package/dist/html/serializer.d.ts +20 -0
package/dist/html/serializer.d.ts.map +1 -0
package/dist/html/serializer.js +132 -0
package/dist/html/serializer.js.map +1 -0
package/dist/index.d.ts +12 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +7 -0
package/dist/index.js.map +1 -0
package/dist/jsx/jsx-runtime.d.ts +213 -0
package/dist/jsx/jsx-runtime.d.ts.map +1 -0
package/dist/jsx/jsx-runtime.js +32 -0
package/dist/jsx/jsx-runtime.js.map +1 -0
package/dist/pipeline/context.d.ts +44 -0
package/dist/pipeline/context.d.ts.map +1 -0
package/dist/pipeline/context.js +2 -0
package/dist/pipeline/context.js.map +1 -0
package/dist/pipeline/renderer.d.ts +40 -0
package/dist/pipeline/renderer.d.ts.map +1 -0
package/dist/pipeline/renderer.js +95 -0
package/dist/pipeline/renderer.js.map +1 -0
package/package.json +38 -0
package/src/error/boundary.ts +80 -0
package/src/error/error-page.ts +137 -0
package/src/error/types.ts +6 -0
package/src/html/escape.ts +90 -0
package/src/html/serializer.ts +161 -0
package/src/index.ts +33 -0
package/src/jsx/jsx-runtime.ts +247 -0
package/src/pipeline/context.ts +45 -0
package/src/pipeline/renderer.ts +138 -0
package/test/unit/error/boundary.test.ts +78 -0
package/test/unit/error/error-page.test.ts +63 -0
package/test/unit/html/escape.test.ts +34 -0
package/test/unit/html/renderer.test.ts +93 -0
package/test/unit/html/serializer.test.ts +141 -0
package/tsconfig.json +15 -0
package/vitest.config.ts +4 -0

package/package.json ADDED Viewed

@@ -0,0 +1,38 @@
+{
+  "name": "@jamx-framework/renderer",
+  "version": "0.1.0",
+  "description": "JAMX Framework — SSR Renderer",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./jsx-runtime": {
+      "import": "./dist/jsx/jsx-runtime.js",
+      "types": "./dist/jsx/jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "import": "./dist/jsx/jsx-runtime.js",
+      "types": "./dist/jsx/jsx-runtime.d.ts"
+    }
+  },
+  "dependencies": {
+    "@jamx-framework/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "clean": "rimraf dist *.tsbuildinfo"
+  }
+}

package/src/error/boundary.ts ADDED Viewed

@@ -0,0 +1,80 @@
+import { HttpException } from "@jamx-framework/core";
+import { renderErrorPage } from "./error-page.js";
+import type { RenderError } from "./types.js";
+export interface BoundaryOptions {
+  isDev: boolean;
+  path?: string;
+}
+export interface BoundaryResult {
+  html: string;
+  statusCode: number;
+  error: RenderError;
+}
+/**
+ * Captura errores durante el render SSR y genera una página de error.
+ *
+ * Uso:
+ *   const result = await ErrorBoundary.wrap(
+ *     () => renderer.render(page, props),
+ *     { isDev: true, path: '/about' }
+ *   )
+ *
+ *   if (result.caught) {
+ *     res.html(result.html, result.statusCode)
+ *   }
+ */
+export class ErrorBoundary {
+  static async wrap<T>(
+    fn: () => Promise<T>,
+    options: BoundaryOptions,
+  ): Promise<
+    { caught: false; value: T } | ({ caught: true } & BoundaryResult)
+  > {
+    try {
+      const value = await fn();
+      return { caught: false, value };
+    } catch (err) {
+      const renderError = ErrorBoundary.toRenderError(err, options.path);
+      const html = renderErrorPage(renderError, options.isDev);
+      return {
+        caught: true,
+        html,
+        statusCode: renderError.statusCode,
+        error: renderError,
+      };
+    }
+  }
+  /**
+   * Convierte cualquier error a RenderError.
+   */
+  static toRenderError(err: unknown, path?: string): RenderError {
+    if (err instanceof HttpException) {
+      return {
+        statusCode: err.statusCode,
+        message: err.message,
+        stack: err.stack,
+        path,
+      };
+    }
+    if (err instanceof Error) {
+      return {
+        statusCode: 500,
+        message: err.message,
+        stack: err.stack,
+        path,
+      };
+    }
+    return {
+      statusCode: 500,
+      message: "An unexpected error occurred",
+      path,
+    };
+  }
+}

package/src/error/error-page.ts ADDED Viewed

@@ -0,0 +1,137 @@
+import type { RenderError } from "./types.js";
+/**
+ * Renderiza una página de error HTML.
+ * En producción no muestra el stack trace.
+ */
+export function renderErrorPage(error: RenderError, isDev: boolean): string {
+  const title = errorTitle(error.statusCode);
+  const stack =
+    isDev && error.stack
+      ? `<pre class="stack">${escapeHtml(error.stack)}</pre>`
+      : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${error.statusCode} — ${title}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0 }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: #0f0f0f;
+      color: #e5e5e5;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .container {
+      max-width: 640px;
+      width: 100%;
+      padding: 2rem;
+    }
+    .code {
+      font-size: 6rem;
+      font-weight: 800;
+      color: #3b82f6;
+      line-height: 1;
+      letter-spacing: -4px;
+    }
+    .title {
+      font-size: 1.5rem;
+      font-weight: 600;
+      margin-top: 0.5rem;
+      color: #f5f5f5;
+    }
+    .message {
+      margin-top: 1rem;
+      color: #a3a3a3;
+      font-size: 0.95rem;
+      line-height: 1.6;
+    }
+    .path {
+      margin-top: 0.5rem;
+      font-size: 0.8rem;
+      color: #525252;
+      font-family: monospace;
+    }
+    .stack {
+      margin-top: 1.5rem;
+      padding: 1rem;
+      background: #171717;
+      border: 1px solid #262626;
+      border-radius: 8px;
+      font-size: 0.75rem;
+      color: #f87171;
+      overflow-x: auto;
+      white-space: pre-wrap;
+      word-break: break-word;
+      line-height: 1.6;
+    }
+    .divider {
+      margin-top: 2rem;
+      border: none;
+      border-top: 1px solid #262626;
+    }
+    .footer {
+      margin-top: 1rem;
+      font-size: 0.75rem;
+      color: #404040;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="code">${error.statusCode}</div>
+    <div class="title">${escapeHtml(title)}</div>
+    <div class="message">${escapeHtml(error.message)}</div>
+    ${error.path ? `<div class="path">${escapeHtml(error.path)}</div>` : ""}
+    ${stack}
+    <hr class="divider">
+    <div class="footer">JAMX Framework</div>
+  </div>
+</body>
+</html>`;
+}
+function errorTitle(statusCode: number): string {
+  switch (statusCode) {
+    case 400:
+      return "Bad Request";
+    case 401:
+      return "Unauthorized";
+    case 403:
+      return "Forbidden";
+    case 404:
+      return "Not Found";
+    case 422:
+      return "Unprocessable Entity";
+    case 500:
+      return "Internal Server Error";
+    case 503:
+      return "Service Unavailable";
+    default:
+      return statusCode >= 500 ? "Server Error" : "Client Error";
+  }
+}
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}

package/src/error/types.ts ADDED Viewed

@@ -0,0 +1,6 @@
+export interface RenderError {
+  statusCode: number;
+  message: string;
+  stack?: string | undefined;
+  path?: string | undefined;
+}

package/src/html/escape.ts ADDED Viewed

@@ -0,0 +1,90 @@
+// packages/renderer/src/html/escape.ts
+/**
+ * Escapa caracteres especiales HTML para prevenir XSS.
+ * Siempre usar esto al renderizar contenido de usuario.
+ */
+export function escapeHtml(value: unknown): string {
+  const str = String(value);
+  let result = "";
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+    switch (char) {
+      case "&":
+        result += "&amp;";
+        break;
+      case "<":
+        result += "&lt;";
+        break;
+      case ">":
+        result += "&gt;";
+        break;
+      case '"':
+        result += "&quot;";
+        break;
+      case "'":
+        result += "&#39;";
+        break;
+      default:
+        result += char;
+    }
+  }
+  return result;
+}
+/**
+ * Tags HTML que no tienen closing tag.
+ */
+export const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+/**
+ * Tags cuyo contenido se renderiza tal cual (sin escapar).
+ */
+export const RAW_TEXT_ELEMENTS = new Set(["script", "style"]);
+/**
+ * Atributos booleanos — se renderizan sin valor si son true.
+ * Ej: <input disabled /> en lugar de <input disabled="true" />
+ */
+export const BOOLEAN_ATTRIBUTES = new Set([
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "ismap",
+  "loop",
+  "multiple",
+  "muted",
+  "nomodule",
+  "novalidate",
+  "open",
+  "readonly",
+  "required",
+  "reversed",
+  "selected",
+  "typemustmatch",
+]);

package/src/html/serializer.ts ADDED Viewed

@@ -0,0 +1,161 @@
+import {
+  escapeHtml,
+  VOID_ELEMENTS,
+  RAW_TEXT_ELEMENTS,
+  BOOLEAN_ATTRIBUTES,
+} from "./escape.js";
+import { Fragment } from "../jsx/jsx-runtime.js";
+import type {
+  JamxNode,
+  JamxElement,
+  ComponentFn,
+  Props,
+} from "../jsx/jsx-runtime.js";
+/**
+ * Serializa un árbol JSX a una string HTML.
+ *
+ * Proceso:
+ * 1. Si el nodo es un string/number → escapar y retornar
+ * 2. Si el nodo es un componente (función) → llamarlo y serializar el resultado
+ * 3. Si el nodo es un elemento HTML → serializar tag + props + children
+ * 4. Si el nodo es un Fragment → serializar solo los children
+ */
+export class HtmlSerializer {
+  serialize(node: JamxNode): string {
+    // Nodos primitivos
+    if (node === null || node === undefined || node === false) return "";
+    if (node === true) return "";
+    if (typeof node === "number") return String(node);
+    if (typeof node === "string") return escapeHtml(node);
+    // Arrays
+    if (Array.isArray(node)) {
+      return node.map((child) => this.serialize(child)).join("");
+    }
+    // Elemento JSX
+    return this.serializeElement(node);
+  }
+  private serializeElement(element: JamxElement): string {
+    const { type, props } = element;
+    // Componente funcional — ejecutar y serializar el resultado
+    if (typeof type === "function") {
+      return this.serializeComponent(type, props);
+    }
+    // Fragment — solo los hijos
+    if (type === Fragment) {
+      return this.serializeChildren(props.children);
+    }
+    // Elemento HTML
+    return this.serializeHtmlElement(type, props);
+  }
+  private serializeComponent(fn: ComponentFn, props: Props): string {
+    try {
+      const result = fn(props);
+      return this.serialize(result);
+    } catch (err) {
+      throw new Error(
+        `Error rendering component '${fn.name || "anonymous"}': ${String(err)}`,
+      );
+    }
+  }
+  private serializeHtmlElement(tag: string, props: Props): string {
+    const { children, ...attrs } = props;
+    const attrString = this.serializeAttributes(attrs);
+    const openTag = attrString ? `<${tag} ${attrString}>` : `<${tag}>`;
+    // Elementos void — no tienen closing tag ni children
+    if (VOID_ELEMENTS.has(tag)) {
+      return openTag;
+    }
+    // Elementos con contenido raw (script, style)
+    if (RAW_TEXT_ELEMENTS.has(tag)) {
+      const rawContent = typeof children === "string" ? children : "";
+      return `${openTag}${rawContent}</${tag}>`;
+    }
+    const childrenHtml = this.serializeChildren(children);
+    return `${openTag}${childrenHtml}</${tag}>`;
+  }
+  private serializeAttributes(attrs: Record<string, unknown>): string {
+    const parts: string[] = [];
+    for (const [key, value] of Object.entries(attrs)) {
+      // Ignorar atributos internos y undefined/null
+      if (key === "key" || value === undefined || value === null) continue;
+      // className → class
+      const attrName =
+        key === "className"
+          ? "class"
+          : key === "htmlFor"
+            ? "for"
+            : key === "tabIndex"
+              ? "tabindex"
+              : camelToKebab(key);
+      // Atributos booleanos
+      if (BOOLEAN_ATTRIBUTES.has(attrName)) {
+        if (value === true) parts.push(attrName);
+        continue;
+      }
+      // style como objeto
+      if (key === "style" && typeof value === "object" && value !== null) {
+        const styleStr = this.serializeStyle(value as Record<string, string>);
+        if (styleStr) parts.push(`style="${escapeHtml(styleStr)}"`);
+        continue;
+      }
+      // false → omitir el atributo
+      if (value === false) continue;
+      // true → atributo sin valor (no booleano, ej: data-active)
+      if (value === true) {
+        parts.push(attrName);
+        continue;
+      }
+      parts.push(`${attrName}="${escapeHtml(value)}"`);
+    }
+    return parts.join(" ");
+  }
+  private serializeStyle(style: Record<string, string>): string {
+    return Object.entries(style)
+      .map(([prop, value]) => `${camelToKebab(prop)}: ${value}`)
+      .join("; ");
+  }
+  private serializeChildren(children: unknown): string {
+    if (children === undefined || children === null) return "";
+    if (Array.isArray(children)) {
+      return children
+        .map((child) => this.serialize(child as JamxNode))
+        .join("");
+    }
+    return this.serialize(children as JamxNode);
+  }
+}
+// ── HELPERS ───────────────────────────────────────────────────────────────
+/**
+ * Convierte camelCase a kebab-case para atributos HTML.
+ * backgroundColor → background-color
+ * dataTestId → data-test-id (los data- ya vienen bien)
+ */
+function camelToKebab(str: string): string {
+  return str.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,33 @@
+export { SSRRenderer } from "./pipeline/renderer.js";
+export { HtmlSerializer } from "./html/serializer.js";
+export {
+  escapeHtml,
+  VOID_ELEMENTS,
+  BOOLEAN_ATTRIBUTES,
+} from "./html/escape.js";
+export { jsx, jsxs, jsxDEV, Fragment } from "./jsx/jsx-runtime.js";
+export type {
+  JamxNode,
+  JamxElement,
+  ComponentFn,
+  Props,
+  JSX,
+  HtmlAttributes,
+} from "./jsx/jsx-runtime.js";
+export type {
+  RenderContext,
+  RenderResult,
+  PageHead,
+} from "./pipeline/context.js";
+export type {
+  PageComponentLike,
+  LayoutComponentLike,
+} from "./pipeline/renderer.js";
+export { ErrorBoundary } from "./error/boundary.js";
+export { renderErrorPage } from "./error/error-page.js";
+export type { RenderError } from "./error/types.js";
+export type { BoundaryOptions, BoundaryResult } from "./error/boundary.js";