@axzydev/axzy_ui_system 1.6.0 → 1.7.1

package/src/json-renderer/catalog/resolve.ts

@@ -0,0 +1,225 @@
+/**
+ * Resolución de un nodo contra el catálogo.
+ *
+ * Aquí es donde el esquema deja de ser texto libre y se convierte en props
+ * seguras: se comprueba el tipo, se filtran las props permitidas, se aplican los
+ * valores por defecto, se coaccionan los tipos y se acumulan los avisos con su
+ * ruta exacta. Nada de esto lanza: un nodo mal formado produce avisos y se pinta
+ * lo que se pueda.
+ */
+
+import { JsonEngineError, issue, type JsonEngineIssue } from "../shared/errors";
+import { formatPath, propPath, type SchemaPath } from "../shared/paths";
+import type { NodeSchema } from "../kernel/types";
+import { GLOBALLY_FORBIDDEN_PROPS, isExcludedType, getExclusionReason, type Catalog, type CatalogEntry, type PropSpec } from "./catalog.props";
+
+/** Resultado de resolver un nodo: props listas para el componente + avisos. */
+export interface ResolvedNode {
+  /** Discriminante: el nodo se pudo resolver. */
+  ok: true;
+  /** Entrada del catálogo que se va a montar. */
+  entry: CatalogEntry;
+  /** Props ya filtradas, con defaults aplicados y tipos coaccionados. */
+  props: Record<string, unknown>;
+  /** Acciones declaradas en el nodo, por nombre de prop (`onClick` → esquema). */
+  actions: Record<string, unknown>;
+  /** Avisos acumulados (tipo desconocido, prop ignorada, valor inválido…). */
+  issues: JsonEngineIssue[];
+}
+
+/** Resultado cuando el nodo no se puede resolver. */
+export interface UnresolvedNode {
+  /** Discriminante: el nodo no se pudo resolver. */
+  ok: false;
+  /** Avisos que explican por qué. */
+  issues: JsonEngineIssue[];
+}
+
+/**
+ * `true` cuando el valor es una **referencia** del esquema (`{ i18n }`,
+ * `{ $state }`, `{ $source }`…).
+ *
+ * Las referencias no se coaccionan: se entregan tal cual para que el host las
+ * resuelva (`resolveValue`). Coaccionarlas aquí las convertiría en `undefined` y
+ * el valor desaparecería antes de poder traducirlo.
+ */
+export function isSchemaReference(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value as Record<string, unknown>);
+  if (keys.length === 0) return false;
+  return keys.some((key) => key === "i18n" || key.startsWith("$"));
+}
+
+/** Coacciona un valor al tipo declarado. Devuelve `undefined` si no es válido. */
+function coerce(value: unknown, spec: PropSpec): unknown {
+  switch (spec.kind) {
+    case "string":
+      if (typeof value === "string") return value;
+      if (typeof value === "number" || typeof value === "boolean") return String(value);
+      return undefined;
+    case "number":
+    case "integer": {
+      if (typeof value === "number" && Number.isFinite(value)) {
+        return spec.kind === "integer" ? Math.trunc(value) : value;
+      }
+      if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) {
+        const parsed = Number(value);
+        return spec.kind === "integer" ? Math.trunc(parsed) : parsed;
+      }
+      return undefined;
+    }
+    case "boolean":
+      if (typeof value === "boolean") return value;
+      if (value === "true") return true;
+      if (value === "false") return false;
+      return undefined;
+    case "enum":
+      if (typeof value !== "string") return undefined;
+      return spec.values?.includes(value) ? value : undefined;
+    case "array":
+      return Array.isArray(value) ? value : undefined;
+    case "object":
+      return value && typeof value === "object" ? value : undefined;
+    default:
+      // `action`, `i18n`, `data`, `columns`, `node`, `nodes`: el valor se
+      // resuelve más tarde (acciones, binding, hijos). Aquí solo se filtra.
+      return value;
+  }
+}
+
+/**
+ * Resuelve un nodo contra el catálogo.
+ *
+ * @example
+ * const resolved = resolveNode({ type: "ITButton", props: { label: "Ir" } }, axzyCatalog, ["content", 0]);
+ * resolved.props.label; // "Ir"
+ */
+export function resolveNode(
+  node: NodeSchema,
+  catalog: Catalog,
+  path: SchemaPath
+): ResolvedNode | UnresolvedNode {
+  const issues: JsonEngineIssue[] = [];
+  const type = node.type;
+
+  if (typeof type !== "string" || type === "") {
+    issues.push(issue("JR021", "El nodo no declara `type`.", formatPath(path), { severity: "error" }));
+    return { ok: false, issues };
+  }
+
+  if (isExcludedType(catalog, type)) {
+    const reason = getExclusionReason(catalog, type);
+    issues.push(
+      issue("JR010", `El tipo \`${type}\` está excluido del catálogo.`, formatPath(path), {
+        severity: "error",
+        hint: reason,
+      })
+    );
+    return { ok: false, issues };
+  }
+
+  const entry = catalog.entries[type];
+  if (!entry) {
+    const known = Object.keys(catalog.entries).slice(0, 8).join(", ");
+    issues.push(
+      issue("JR010", `El tipo \`${type}\` no está en el catálogo.`, formatPath(path), {
+        severity: "error",
+        hint: `Tipos disponibles (primeros 8): ${known}…`,
+      })
+    );
+    return { ok: false, issues };
+  }
+
+  const specs = entry.props ?? {};
+  const props: Record<string, unknown> = {};
+  const actions: Record<string, unknown> = {};
+  const input = node.props ?? {};
+
+  // 1. Valores por defecto declarados en el catálogo.
+  for (const [name, spec] of Object.entries(specs)) {
+    if (spec.default !== undefined) props[name] = spec.default;
+  }
+
+  // 2. Props aportadas por el esquema, filtradas por la lista blanca.
+  for (const [name, raw] of Object.entries(input)) {
+    const forbiddenByEntry = entry.forbidden?.includes(name);
+    const forbiddenGlobally = GLOBALLY_FORBIDDEN_PROPS.includes(name);
+
+    if (forbiddenByEntry || forbiddenGlobally) {
+      issues.push(
+        issue("JR011", `La prop \`${name}\` está prohibida en \`${type}\`.`, formatPath(propPath(path, name)), {
+          severity: "warning",
+          hint: "Los nodos React se declaran como hijos del esquema, no como props.",
+        })
+      );
+      continue;
+    }
+
+    const spec = specs[name];
+    if (!spec) {
+      issues.push(
+        issue("JR011", `La prop \`${name}\` no está declarada para \`${type}\`.`, formatPath(propPath(path, name)), {
+          severity: "warning",
+          hint: "Se ignora. Si es necesaria, añádela al catálogo con su tipo.",
+        })
+      );
+      continue;
+    }
+
+    if (spec.kind === "action") {
+      actions[name] = raw;
+      continue;
+    }
+
+    // Una referencia (`{ i18n: "clave" }`, `{ $state: "x" }`) se pasa tal cual:
+    // el host decide su valor final y el catálogo no debe coaccionarla.
+    if (isSchemaReference(raw)) {
+      props[name] = raw;
+      continue;
+    }
+
+    const value = coerce(raw, spec);
+    if (value === undefined) {
+      issues.push(
+        issue(
+          "JR011",
+          `Valor inválido para \`${name}\` en \`${type}\`.`,
+          formatPath(propPath(path, name)),
+          { severity: "warning", hint: spec.values ? `Admitidos: ${spec.values.join(", ")}` : `Se esperaba ${spec.kind}.` }
+        )
+      );
+      continue;
+    }
+    props[name] = value;
+  }
+
+  // 3. Props obligatorias que faltan.
+  for (const [name, spec] of Object.entries(specs)) {
+    if (spec.required && props[name] === undefined) {
+      issues.push(
+        issue("JR011", `Falta la prop obligatoria \`${name}\` en \`${type}\`.`, formatPath(propPath(path, name)), {
+          severity: "error",
+        })
+      );
+    }
+  }
+
+  // 4. Hijos declarados sin que el componente los acepte.
+  if (node.children !== undefined && !entry.children) {
+    issues.push(
+      issue("JR011", `\`${type}\` no acepta \`children\`.`, formatPath([...path, "children"]), {
+        severity: "warning",
+        hint: "Los hijos se ignoran.",
+      })
+    );
+  }
+
+  return { ok: true, entry, props, actions, issues };
+}
+
+/** Convierte un error del motor en aviso para el informe. */
+export function toIssue(error: unknown, path: SchemaPath, fallback = "Fallo del motor"): JsonEngineIssue {
+  if (error instanceof JsonEngineError) return error.toIssue();
+  const message = error instanceof Error ? error.message : String(error);
+  return issue("JR012", message || fallback, formatPath(path), { severity: "error" });
+}

package/src/json-renderer/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Motor de pantallas declarativas de AXZY UI System.
+ *
+ * Convierte un esquema JSON versionado en una pantalla completa, tratándolo
+ * siempre como **entrada no confiable**: lista blanca de componentes y props,
+ * sin código, sin red y sin HTML. El caso de uso principal es la UI generada por
+ * IA, así que el esquema puede llegar **a trozos** y el motor pinta lo que ya
+ * está cerrado.
+ *
+ * Alcance y plan: `docs/json-renderer/ALCANCE.md` y `PLAN-IMPLEMENTACION.md`.
+ *
+ * @example
+ * ```tsx
+ * const schema = { version: 1, id: "demo", content: { type: "ITText", text: "Hola" } };
+ * <ITSchemaRenderer schema={schema} />
+ * ```
+ */
+
+/* ── Kernel ─────────────────────────────────────────────────────────────── */
+export { ITSchemaRenderer, default as ITJsonScreen } from "./kernel/SchemaRenderer";
+export { NodeBoundary } from "./kernel/NodeBoundary";
+export { renderNode, childList, hasChildren } from "./kernel/renderNode";
+export { auditTree, countPendingNodes } from "./kernel/partial";
+export type { ITJsonRenderEngineProps } from "./kernel/schemaRenderer.props";
+export type {
+  ScreenSchema,
+  NodeSchema,
+  SchemaValue,
+  SchemaReference,
+  WhenSchema,
+  ActionSchema,
+  EffectSchema,
+  DataSourceSchema,
+  NodeStatus,
+} from "./kernel/types";
+
+/* ── Catálogo ──────────────────────────────────────────────────────────── */
+export { axzyCatalog, axzyCatalogTypes, AXZY_CATALOG_ENTRIES, AXZY_EXCLUDED_TYPES } from "./catalog/axzyCatalog";
+export {
+  createCatalog,
+  getCatalogEntry,
+  isExcludedType,
+  getExclusionReason,
+  GLOBALLY_FORBIDDEN_PROPS,
+} from "./catalog/catalog.props";
+export { resolveNode } from "./catalog/resolve";
+export type { Catalog, CatalogEntry, PropSpec, PropKind } from "./catalog/catalog.props";
+export type { ResolvedNode, UnresolvedNode } from "./catalog/resolve";
+
+/* ── Validación y versionado ───────────────────────────────────────────── */
+export { validateSchema, CURRENT_SCHEMA_VERSION } from "./validation/validate";
+export { migrateSchema, DEFAULT_MIGRATIONS } from "./validation/migrate";
+export type { ValidationReport, ValidationVerdict, ValidateOptions } from "./validation/validate";
+export type { SchemaMigration, MigrationRegistry, MigrationResult } from "./validation/migrate";
+
+/* ── Contrato de vocabulario (para el emisor) ──────────────────────────── */
+export { buildVocabularyContract, formatVocabularyForPrompt } from "./vocabulary/buildContract";
+export type { VocabularyContract, ComponentContract, PropContract } from "./vocabulary/buildContract";
+
+/* ── Streaming ─────────────────────────────────────────────────────────── */
+export { parsePartialSchema, isNodePending } from "./stream/tolerantParse";
+export type { PartialParseResult, StreamState } from "./stream/tolerantParse";
+
+/* ── Compartido ────────────────────────────────────────────────────────── */
+export { JsonEngineError, issue } from "./shared/errors";
+export type { JsonEngineIssue, JsonEngineCode, JsonEngineSeverity } from "./shared/errors";
+export { formatPath, parsePath, readPath, hasPath, pushPath, propPath } from "./shared/paths";
+export type { SchemaPath, PathSegment } from "./shared/paths";
+export { DEFAULT_LIMITS, resolveLimits, createLimitTracker } from "./shared/limits";
+export type { EngineLimits, LimitTracker } from "./shared/limits";

package/src/json-renderer/kernel/NodeBoundary.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { JsonEngineError } from "../shared/errors";
+
+/** Props de `NodeBoundary`. */
+export interface NodeBoundaryProps {
+  /** Ruta del nodo dentro del esquema, para el aviso. */
+  path: string;
+  /** Qué pintar si el subárbol falla. */
+  fallback?: React.ReactNode;
+  /** Se llama con el error y su ruta para acumularlo en el informe. */
+  onError?: (error: Error, path: string) => void;
+  /** Subárbol del nodo. */
+  children: React.ReactNode;
+}
+
+/** Estado interno del boundary. */
+interface NodeBoundaryState {
+  failed: boolean;
+}
+
+/**
+ * Aísla el fallo de un nodo: si un componente del catálogo lanza durante el
+ * render, solo se pierde ese subárbol y el resto de la pantalla sigue viva
+ * (aviso `JR012`).
+ *
+ * @example
+ * <NodeBoundary path="content[0]" fallback={<p>No se pudo pintar</p>}>
+ *   <ITCard />
+ * </NodeBoundary>
+ */
+export class NodeBoundary extends React.Component<NodeBoundaryProps, NodeBoundaryState> {
+  state: NodeBoundaryState = { failed: false };
+
+  static getDerivedStateFromError(): NodeBoundaryState {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    this.props.onError?.(error, this.props.path);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.failed) return this.props.fallback ?? null;
+    return this.props.children;
+  }
+}
+
+/** Extrae un `Error` de cualquier valor lanzado. */
+export function asError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  if (value instanceof JsonEngineError) return value;
+  return new Error(typeof value === "string" ? value : "Fallo desconocido al pintar el nodo");
+}

package/src/json-renderer/kernel/SchemaRenderer.tsx

@@ -0,0 +1,197 @@
+import React, { useEffect, useMemo, useRef } from "react";
+import type { Catalog } from "../catalog/catalog.props";
+import { axzyCatalog } from "../catalog/axzyCatalog";
+import type { JsonEngineIssue } from "../shared/errors";
+import { resolveLimits, type EngineLimits } from "../shared/limits";
+import type { SchemaPath } from "../shared/paths";
+import { NodeBoundary } from "./NodeBoundary";
+import { auditTree } from "./partial";
+import { childList, renderNode } from "./renderNode";
+import type { ITJsonRenderEngineProps } from "./schemaRenderer.props";
+import type { NodeSchema } from "./types";
+
+/** Contexto que comparten los nodos durante un render. */
+interface RenderContext {
+  catalog: Catalog;
+  /** Ids declarados por los nodos, para verificar que llegan al DOM. */
+  nodeIds: Set<string>;
+  limits: EngineLimits;
+  issues: JsonEngineIssue[];
+  onIssue?: (issue: JsonEngineIssue) => void;
+  resolveValue?: ITJsonRenderEngineProps["resolveValue"];
+  resolveAction?: ITJsonRenderEngineProps["resolveAction"];
+  pendingFallback?: React.ReactNode;
+}
+
+/**
+ * Recorre un nodo y sus hijos, acumulando avisos y aislando fallos.
+ *
+ * La recursión se hace aquí (y no dentro de `renderNode`) para que el
+ * presupuesto y los avisos se compartan en todo el árbol.
+ */
+function renderTree(node: NodeSchema, path: SchemaPath, context: RenderContext, level: number): React.ReactNode {
+  if (!node || typeof node !== "object") return null;
+  if (level > context.limits.maxDepth) return null;
+
+  // Todos los avisos del subárbol van a parar al mismo array del contexto: el
+  // resolutor escribe ahí directamente y el boundary informa por `onIssue`.
+  const issues = context.issues;
+
+  if (node.id) context.nodeIds.add(node.id);
+
+  const reportIssue = (issue: JsonEngineIssue) => {
+    issues.push(issue);
+    context.onIssue?.(issue);
+  };
+
+  const issuesBefore = issues.length;
+
+  const element = renderNode(node, {
+    catalog: context.catalog,
+    path,
+    issues,
+    resolveValue: context.resolveValue,
+    resolveAction: context.resolveAction,
+    pendingFallback: context.pendingFallback,
+    renderChildren: (current, currentPath) => {
+      const children = childList(current);
+      if (children.length === 0) return undefined;
+      return children.map((child, index) =>
+        renderTree(child, [...currentPath, "children", index], context, level + 1)
+      );
+    },
+  });
+
+  // El resolutor acumula en el array compartido; aquí se reenvían los nuevos
+  // para que `onIssue` los reciba todos (incluidos los de tipos desconocidos).
+  for (let index = issuesBefore; index < issues.length; index += 1) {
+    context.onIssue?.(issues[index]);
+  }
+
+  // El fallback declarado por el nodo se usa si algo del subárbol falla.
+  const fallback = node.fallback
+    ? renderTree(node.fallback, [...path, "fallback"], context, level + 1)
+    : context.pendingFallback ?? null;
+
+  const wrapped = (
+    <NodeBoundary
+      key={String(path.join("-"))}
+      path={path.join(".")}
+      fallback={fallback}
+      onError={(error, errorPath) =>
+        reportIssue({
+          code: "JR012",
+          severity: "error",
+          message: error.message,
+          path: errorPath,
+          hint: "El nodo se ha aislado; el resto de la pantalla sigue pintándose.",
+        })
+      }
+    >
+      {element}
+    </NodeBoundary>
+  );
+
+  return wrapped;
+}
+
+/**
+ * Pinta una pantalla completa a partir de un esquema.
+ *
+ * Nunca lanza por culpa del esquema: los problemas se convierten en avisos que
+ * se entregan por `onIssue` (y se acumulan en `issuesRef` si quieres leerlos).
+ *
+ * @example
+ * <ITSchemaRenderer schema={{ version: 1, id: "demo", content: { type: "ITText", text: "Hola" } }} />
+ *
+ * @example
+ * <ITSchemaRenderer schema={schema} onIssue={(issue) => console.warn(issue.code, issue.path)} />
+ */
+export function ITSchemaRenderer({
+  schema,
+  catalog = axzyCatalog,
+  limits,
+  resolveValue,
+  resolveAction,
+  pendingFallback,
+  onIssue,
+  className,
+}: ITJsonRenderEngineProps) {
+  const resolvedLimits = useMemo(() => resolveLimits(limits), [limits]);
+  // Un único array de avisos por render: el resolutor y los boundaries escriben
+  // en él, así que no se pierde ninguno por el camino.
+  const issues: JsonEngineIssue[] = [];
+  // Ids que el esquema declara y que deben acabar en el DOM (anclas, deep links).
+  const nodeIds = new Set<string>();
+
+  // El recuento va antes del render para poder recortar y avisar sin montar nada.
+  const audit = useMemo(
+    () => (schema ? auditTree(schema, resolvedLimits) : null),
+    [schema, resolvedLimits]
+  );
+
+  const context = useMemo<RenderContext>(
+    () => ({
+      catalog,
+      nodeIds,
+      limits: resolvedLimits,
+      issues,
+      onIssue,
+      resolveValue,
+      resolveAction,
+      pendingFallback,
+    }),
+    // `issues` es un array nuevo en cada render a propósito: acumular avisos
+    // entre renders duplicaría los avisos de esquemas que no han cambiado.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [catalog, resolvedLimits, onIssue, resolveValue, resolveAction, pendingFallback]
+  );
+
+  const content = schema
+    ? (Array.isArray(schema.content) ? schema.content : [schema.content]).filter(
+        (node): node is NodeSchema => Boolean(node) && typeof node === "object"
+      )
+    : [];
+  const children = content
+    .slice(0, resolvedLimits.maxNodes)
+    .map((node, index) => renderTree(node, ["content", index], context, 0))
+    .filter(Boolean);
+
+  // Todos los avisos del render + los del recuento, sin duplicar por código y ruta.
+  const collected: JsonEngineIssue[] = [...(audit?.issues ?? []), ...issues];
+  const signature = collected.map((issue) => `${issue.code}:${issue.path}`).join("|");
+
+  // Se entregan después del commit: llamar a `onIssue` (que puede hacer setState
+  // en el padre) durante el render sería un error de React.
+  const reported = useRef<string>("");
+  useEffect(() => {
+    const all = [...collected];
+
+    // Un `id` que no existe en el DOM es un fallo silencioso: el componente no
+    // reenvía props al elemento, así que el ancla no funcionaría. Se avisa.
+    for (const id of nodeIds) {
+      if (!document.getElementById(id)) {
+        all.push({
+          code: "JR014",
+          severity: "warning",
+          message: `El \`id\` "${id}" no llegó al DOM.`,
+          path: id,
+          hint: "El componente no reenvía props al elemento. Pon el id en un nodo que sí lo haga (por ejemplo ITText) o en un contenedor del host.",
+        });
+      }
+    }
+
+    const firma = all.map((issue) => `${issue.code}:${issue.path}`).join("|");
+    if (!onIssue || reported.current === firma) return;
+    reported.current = firma;
+    for (const issue of all) onIssue(issue);
+    // `all` se deriva de la firma; la firma es la dependencia real.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [signature, onIssue]);
+
+  if (!schema || children.length === 0) return null;
+
+  return className ? <div className={className}>{children}</div> : <>{children}</>;
+}
+
+export default ITSchemaRenderer;