@axzydev/axzy_ui_system 1.7.3 → 1.7.4

package/src/json-renderer/stream/useSchemaStream.test.tsx

@@ -0,0 +1,143 @@
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { useSchemaStream, type StreamSource } from "./useSchemaStream";
+
+/** Documento de ejemplo que llega en trozos. */
+const DOCUMENTO = JSON.stringify({
+  version: 1,
+  id: "stream",
+  content: [
+    { type: "ITText", text: "Hola" },
+    { type: "ITText", text: "Mundo" },
+  ],
+});
+
+/** Parte un texto en trozos de tamaño fijo, con una pausa entre ellos. */
+async function* trozos(texto: string, tamano: number, pausaMs = 1): AsyncGenerator<string> {
+  for (let indice = 0; indice < texto.length; indice += tamano) {
+    await new Promise((resolve) => setTimeout(resolve, pausaMs));
+    yield texto.slice(indice, indice + tamano);
+  }
+}
+
+/** Espera a que la fuente termine de emitir. */
+const hastaTerminar = (result: { current: { streaming: boolean } }) => waitFor(() => expect(result.current.streaming).toBe(false));
+
+describe("useSchemaStream: fuentes", () => {
+  it("una cadena completa se pinta de una vez, sin estar en streaming", async () => {
+    const { result } = renderHook(() => useSchemaStream(DOCUMENTO));
+    await hastaTerminar(result);
+    expect(result.current.tree?.id).toBe("stream");
+    expect(result.current.status).toBe("complete");
+    expect(result.current.issues).toEqual([]);
+    expect(result.current.text).toBe(DOCUMENTO);
+  });
+
+  it("una cadena sin cerrar avisa con JR080 y conserva lo que sí es válido", async () => {
+    const { result } = renderHook(() => useSchemaStream('{"version":1,"id":"x","content":{"type":"ITText","text":"ho'));
+    await hastaTerminar(result);
+    expect(result.current.status).not.toBe("complete");
+    expect(result.current.issues.map((aviso) => aviso.code)).toContain("JR080");
+    expect(result.current.tree).not.toBeNull();
+  });
+
+  it("un iterable asíncrono muestra árboles parciales y termina con el documento entero", async () => {
+    const vistos: (string | null)[] = [];
+    // La fuente se crea fuera del render: una fuente nueva en cada render relanzaría el stream.
+    const fuente = trozos(DOCUMENTO, 9);
+    const { result } = renderHook(() => {
+      const estado = useSchemaStream(fuente);
+      vistos.push(estado.tree?.id ?? null);
+      return estado;
+    });
+    await hastaTerminar(result);
+    expect(result.current.text).toBe(DOCUMENTO);
+    expect(result.current.status).toBe("complete");
+    expect(result.current.issues).toEqual([]);
+    // Hubo renders intermedios con árbol: el documento se fue pintando.
+    expect(vistos.filter((id) => id === "stream").length).toBeGreaterThan(1);
+  });
+
+  it("un ReadableStream de texto funciona igual que un iterable", async () => {
+    const readable = new ReadableStream<string>({
+      start(controller) {
+        for (let indice = 0; indice < DOCUMENTO.length; indice += 12) controller.enqueue(DOCUMENTO.slice(indice, indice + 12));
+        controller.close();
+      },
+    });
+    const { result } = renderHook(() => useSchemaStream(readable));
+    await hastaTerminar(result);
+    expect(result.current.text).toBe(DOCUMENTO);
+    expect(result.current.status).toBe("complete");
+  });
+
+  it("si la fuente falla a mitad, se conserva el último árbol válido y se avisa con JR080", async () => {
+    async function* fallando(): AsyncGenerator<string> {
+      yield DOCUMENTO.slice(0, 60);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      throw new Error("red caída");
+    }
+    const fuente = fallando();
+    const { result } = renderHook(() => useSchemaStream(fuente));
+    await hastaTerminar(result);
+    const aviso = result.current.issues.find((item) => item.code === "JR080");
+    expect(aviso?.severity).toBe("error");
+    expect(aviso?.message).toContain("red caída");
+  });
+
+  it("si el texto deja de ser recuperable, el árbol no se rompe: se queda el último válido", async () => {
+    const fuente = trozos(DOCUMENTO.slice(0, 40) + "@@@", 8);
+    const { result } = renderHook(() => useSchemaStream(fuente));
+    await hastaTerminar(result);
+    expect(result.current.tree?.id).toBe("stream");
+  });
+
+  it("sin fuente el estado está vacío", () => {
+    const { result } = renderHook(() => useSchemaStream(null));
+    expect(result.current.tree).toBeNull();
+    expect(result.current.streaming).toBe(false);
+  });
+});
+
+describe("useSchemaStream: montajes y cancelación", () => {
+  it("con StrictMode (doble montaje) no se pierde ni se duplica ningún trozo", async () => {
+    const fuente = trozos(DOCUMENTO, 7, 2);
+    const { result } = renderHook(() => useSchemaStream(fuente), {
+      wrapper: ({ children }) => <React.StrictMode>{children}</React.StrictMode>,
+    });
+    await hastaTerminar(result);
+    expect(result.current.text).toBe(DOCUMENTO);
+    expect(result.current.issues).toEqual([]);
+  });
+
+  it("al desmontar, la fuente recibe return() y deja de emitir", async () => {
+    let cerrada = false;
+    async function* larga(): AsyncGenerator<string> {
+      try {
+        for (let indice = 0; indice < 1000; indice += 1) {
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          yield "x";
+        }
+      } finally {
+        cerrada = true;
+      }
+    }
+    const fuente = larga();
+    const { unmount } = renderHook(() => useSchemaStream(fuente));
+    await new Promise((resolve) => setTimeout(resolve, 15));
+    unmount();
+    await waitFor(() => expect(cerrada).toBe(true));
+  });
+
+  it("cambiar de fuente reinicia el estado con la nueva", async () => {
+    const { result, rerender } = renderHook(({ fuente }: { fuente: StreamSource }) => useSchemaStream(fuente), {
+      initialProps: { fuente: '{"version":1,"id":"primera","content":{"type":"ITText","text":"a"}}' },
+    });
+    await hastaTerminar(result);
+    expect(result.current.tree?.id).toBe("primera");
+
+    rerender({ fuente: '{"version":1,"id":"segunda","content":{"type":"ITText","text":"b"}}' });
+    await waitFor(() => expect(result.current.tree?.id).toBe("segunda"));
+  });
+});

package/src/json-renderer/stream/useSchemaStream.ts

@@ -0,0 +1,227 @@
+/**
+ * `useSchemaStream`: pinta un esquema mientras llega por trozos.
+ *
+ * Acepta una fuente completa (`string`), un iterable asíncrono o un `ReadableStream` de
+ * texto. Acumula el texto, lo parsea en modo tolerante con cada trozo y devuelve el último
+ * árbol válido. Lo que aún no está cerrado no se pinta a medias (ver `pendingFallback`).
+ *
+ * Garantías:
+ *
+ * - **Sin pérdida con StrictMode:** el texto acumulado vive en un registro asociado a la
+ *   fuente, no en el efecto. Si React monta dos veces, el segundo montaje continúa donde
+ *   quedó el primero; ningún fragmento se pierde ni se duplica.
+ * - **Cancelación:** si el componente deja de usar la fuente, el registro se cierra y se
+ *   devuelve el control a la fuente (`return()` del iterable, `cancel()` del stream).
+ * - **Sin árbol roto:** si el texto deja de ser recuperable, se conserva el último árbol
+ *   válido. Un stream que falla o termina sin cerrar avisa con `JR080`.
+ *
+ * **La fuente debe ser estable entre renders.** Crea el iterable o el stream una vez
+ * (en un estado, o fuera del componente) y pásalo tal cual. Crearlo dentro del render
+ * arranca un stream nuevo en cada render.
+ *
+ * @example
+ * const { tree, streaming, issues } = useSchemaStream(respuestaDelModelo);
+ * <ITSchemaRenderer schema={tree} onIssue={registrar} pendingFallback={<ITSkeleton />} />
+ */
+
+import { useEffect, useState } from "react";
+import type { ScreenSchema } from "../kernel/types";
+import { issue, type JsonEngineIssue } from "../shared/errors";
+import { parsePartialSchema, type StreamState } from "./tolerantParse";
+
+/** Fuente de un esquema que llega por trozos. */
+export type StreamSource = string | AsyncIterable<string> | ReadableStream<string>;
+
+/** Estado inicial: nada recibido todavía. */
+const VACIO: StreamState = {
+  tree: null,
+  status: "complete",
+  broken: false,
+  pendingNodes: 0,
+  streaming: false,
+  text: "",
+  issues: [],
+};
+
+/** Registro compartido de una fuente: texto acumulado, iterador y avisos. */
+interface Grabacion {
+  texto: string;
+  iterador: AsyncIterator<string> | null;
+  terminado: boolean;
+  error: string | null;
+  avisos: JsonEngineIssue[];
+  /** Montajes que la están usando ahora. Si llega a cero, la fuente se cancela. */
+  activos: number;
+  /** Último árbol válido: se conserva cuando el texto deja de ser recuperable. */
+  ultimoValido: ScreenSchema | null;
+  /** `true` cuando los avisos de cierre ya se añadieron (para no duplicarlos). */
+  cerrada: boolean;
+  /** `true` cuando la fuente se cortó desde fuera: no es un fin de stream. */
+  cancelada: boolean;
+}
+
+/** Un registro por fuente. Al soltarse la fuente, el registro se libera solo. */
+const grabaciones = new WeakMap<object, Grabacion>();
+
+/** `true` cuando el valor es un iterable asíncrono. */
+function esAsyncIterable(value: unknown): value is AsyncIterable<string> {
+  return value !== null && typeof value === "object" && typeof (value as AsyncIterable<string>)[Symbol.asyncIterator] === "function";
+}
+
+/** Convierte un `ReadableStream` de texto en un generador asíncrono. Cancelar el generador cancela el stream. */
+async function* desdeReadable(readable: ReadableStream<string>): AsyncGenerator<string> {
+  const reader = readable.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+/** Mensaje legible de un error de la fuente. */
+function mensajeDe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Crea el registro de una fuente nueva. */
+function crearGrabacion(source: StreamSource): Grabacion {
+  const iterador: AsyncIterator<string> | null =
+    typeof source === "string" ? null : esAsyncIterable(source) ? source[Symbol.asyncIterator]() : desdeReadable(source)[Symbol.asyncIterator]();
+  return {
+    texto: typeof source === "string" ? source : "",
+    iterador,
+    terminado: typeof source === "string",
+    error: null,
+    avisos: [],
+    activos: 0,
+    ultimoValido: null,
+    cerrada: false,
+    cancelada: false,
+  };
+}
+
+/** Estado que ve el componente a partir del texto acumulado. */
+function estadoDe(grab: Grabacion, streaming: boolean): StreamState {
+  const parcial = parsePartialSchema(grab.texto);
+  if (!parcial.broken && parcial.tree) grab.ultimoValido = parcial.tree;
+  return {
+    tree: parcial.broken ? grab.ultimoValido : parcial.tree,
+    status: parcial.status,
+    broken: parcial.broken,
+    pendingNodes: parcial.pendingNodes,
+    streaming,
+    text: grab.texto,
+    issues: [...grab.avisos],
+  };
+}
+
+/** Al terminar la fuente: avisa si el stream falló o si el JSON quedó sin cerrar. */
+function cerrarGrabacion(grab: Grabacion): void {
+  if (grab.cerrada || grab.cancelada) return;
+  grab.cerrada = true;
+  if (grab.error !== null) {
+    grab.avisos.push(issue("JR080", `El stream falló: ${grab.error}. Se conserva el último árbol válido.`, "", { severity: "error" }));
+    return;
+  }
+  const parcial = parsePartialSchema(grab.texto);
+  if (parcial.broken || parcial.status !== "complete") {
+    grab.avisos.push(
+      issue("JR080", "El stream terminó con el JSON sin cerrar. Se conserva el último árbol válido.", "", {
+        severity: "warning",
+        hint: "Revisa que el emisor cierre todas las llaves y corchetes.",
+      })
+    );
+  }
+}
+
+/**
+ * Consume la fuente sin perder fragmentos y avisa a cada trozo (`onTrozo`) y al terminar.
+ *
+ * Un trozo que ya se pidió se guarda aunque este montaje se haya soltado: el siguiente
+ * montaje lo encuentra en el registro. Así StrictMode no pierde nada.
+ */
+async function consumir(grab: Grabacion, cancelado: () => boolean, onTrozo: () => void): Promise<void> {
+  while (!grab.terminado && grab.iterador) {
+    let paso: IteratorResult<string>;
+    try {
+      paso = await grab.iterador.next();
+    } catch (error) {
+      grab.error = mensajeDe(error);
+      grab.terminado = true;
+      break;
+    }
+    if (paso.done) {
+      grab.terminado = true;
+      break;
+    }
+    grab.texto += String(paso.value);
+    if (!cancelado()) onTrozo();
+    if (cancelado()) return;
+  }
+  if (grab.terminado) cerrarGrabacion(grab);
+}
+
+/**
+ * Devuelve el estado de un esquema que llega por trozos.
+ *
+ * @example
+ * const estado = useSchemaStream(stream);
+ * estado.tree;      // árbol pintable, o null si aún no hay nada válido
+ * estado.streaming; // true mientras la fuente sigue emitiendo
+ */
+export function useSchemaStream(source: StreamSource | null | undefined): StreamState {
+  const [estado, setEstado] = useState<StreamState>(VACIO);
+
+  useEffect(() => {
+    if (source === null || source === undefined) {
+      setEstado(VACIO);
+      return;
+    }
+
+    // Una cadena no puede ser clave de WeakMap, y ya está entera: basta un registro efímero.
+    // Los iterables y los streams se registran para sobrevivir a StrictMode.
+    let registro: Grabacion;
+    if (typeof source === "string") {
+      registro = crearGrabacion(source);
+    } else {
+      const existente = grabaciones.get(source);
+      registro = existente ?? crearGrabacion(source);
+      if (!existente) grabaciones.set(source, registro);
+    }
+    registro.activos += 1;
+
+    let cancelado = false;
+    // Primero se arranca el proceso: una cadena se cierra de forma síncrona (y sus avisos
+    // quedan ya en el registro), así que el estado inicial los incluye.
+    const proceso = consumir(
+      registro,
+      () => cancelado,
+      () => setEstado(estadoDe(registro, true))
+    );
+    setEstado(estadoDe(registro, !registro.terminado));
+
+    void proceso.then(() => {
+      if (!cancelado) setEstado(estadoDe(registro, false));
+    });
+
+    return () => {
+      cancelado = true;
+      registro.activos -= 1;
+      // Si nadie más usa la fuente tras el ciclo de montaje (StrictMode monta dos veces de
+      // forma síncrona), se devuelve el control a la fuente.
+      setTimeout(() => {
+        if (registro.activos === 0 && !registro.terminado && registro.iterador) {
+          registro.terminado = true;
+          registro.cancelada = true;
+          void registro.iterador.return?.(undefined);
+        }
+      }, 0);
+    };
+  }, [source]);
+
+  return estado;
+}

package/src/json-renderer/validation/jsonSchema.test.ts

@@ -0,0 +1,105 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020.js";
+import { axzyCatalog } from "../catalog/axzyCatalog";
+import { buildRoutesSchema, buildScreenSchema } from "./jsonSchema";
+
+const DOCS = join(process.cwd(), "docs/json-renderer");
+const DEMO = join(process.cwd(), "public/demo/app");
+
+/** Lee un JSON versionado. */
+const leer = (ruta: string) => JSON.parse(readFileSync(ruta, "utf8")) as Record<string, unknown>;
+
+/** Validador compilado con las mismas opciones que el tester de `scripts/json-renderer/check.mjs`. */
+function validador(schema: Record<string, unknown>) {
+  const ajv = new Ajv2020({ allErrors: true, strict: true, allowUnionTypes: true, strictRequired: false });
+  return ajv.compile(schema);
+}
+
+const screen = validador(buildScreenSchema());
+const routes = validador(buildRoutesSchema());
+
+describe("schemas generados", () => {
+  it("los archivos versionados coinciden con el generador (regenera con pnpm docs:json-renderer)", () => {
+    expect(leer(join(DOCS, "screen.schema.json"))).toEqual(JSON.parse(JSON.stringify(buildScreenSchema())));
+    expect(leer(join(DOCS, "routes.schema.json"))).toEqual(JSON.parse(JSON.stringify(buildRoutesSchema())));
+  });
+
+  it("cubre todo el catálogo: cada componente es un tipo válido", () => {
+    const schema = buildScreenSchema() as { $defs: { node: { properties: { type: { enum: string[] } } } } };
+    const tipos = schema.$defs.node.properties.type.enum;
+    for (const tipo of Object.keys(axzyCatalog.entries)) {
+      expect(tipos, tipo).toContain(tipo);
+    }
+    expect(tipos).toEqual(expect.arrayContaining(["slot", "form"]));
+  });
+
+  it("cada prop del catálogo aparece en el schema de su tipo (autocompletado completo)", () => {
+    const schema = buildScreenSchema() as { $defs: { node: { allOf: { if: { properties: { type: { const: string } } }; then: { properties: { props?: { properties?: Record<string, unknown> } } } }[] } } };
+    for (const [tipo, entrada] of Object.entries(axzyCatalog.entries)) {
+      const regla = schema.$defs.node.allOf.find((item) => item.if.properties.type.const === tipo);
+      expect(regla, tipo).toBeDefined();
+      const propiedades = regla?.then.properties.props?.properties ?? {};
+      for (const prop of Object.keys(entrada.props ?? {})) {
+        expect(propiedades, `${tipo}.${prop}`).toHaveProperty([prop]);
+      }
+    }
+  });
+});
+
+describe("documentos del demo cumplen el schema", () => {
+  const paginas = readdirSync(DEMO).filter((archivo) => archivo.endsWith(".json") && archivo !== "layout.json" && archivo !== "routes.json");
+
+  it.each(paginas)("%s es una pantalla válida", (archivo) => {
+    const ok = screen(leer(join(DEMO, archivo)));
+    expect(ok, JSON.stringify(screen.errors)).toBe(true);
+  });
+
+  it("routes.json es un documento de rutas válido", () => {
+    expect(routes(leer(join(DEMO, "routes.json"))), JSON.stringify(routes.errors)).toBe(true);
+  });
+});
+
+describe("el schema rechaza lo que el motor no pinta", () => {
+  const pantalla = (content: unknown) => ({ version: 1, id: "x", content });
+
+  it("un tipo fuera del catálogo", () => {
+    expect(screen(pantalla({ type: "ITInventado" }))).toBe(false);
+  });
+
+  it("una prop que el componente no declara", () => {
+    expect(screen(pantalla({ type: "ITButton", props: { label: "Hola", colorRaro: "red" } }))).toBe(false);
+  });
+
+  it("un valor de enum fuera de su lista", () => {
+    expect(screen(pantalla({ type: "ITButton", props: { label: "Hola", size: "gigante" } }))).toBe(false);
+  });
+
+  it("un slot sin nombre", () => {
+    expect(screen(pantalla({ type: "slot", props: { titulo: "x" } }))).toBe(false);
+  });
+
+  it("un campo de formulario con tipo no admitido", () => {
+    expect(screen(pantalla({ type: "form", props: { fields: [{ name: "edad", kind: "number" }] } }))).toBe(false);
+  });
+
+  it("una referencia que no existe, como `$row` fuera de una tabla", () => {
+    expect(screen(pantalla({ type: "ITText", text: { $row: "nombre" } }))).toBe(false);
+  });
+
+  it("un hijo en un componente que no admite hijos", () => {
+    expect(screen(pantalla({ type: "ITDivider", children: [{ type: "ITText", text: "y" }] }))).toBe(false);
+    expect(screen(pantalla({ type: "ITCard", children: [{ type: "ITText", text: "y" }] }))).toBe(true);
+  });
+
+  it("una ruta grupo con page, o una hoja sin page", () => {
+    expect(routes({ version: 1, routes: [{ id: "g", page: "x", children: [{ id: "h", page: "y" }] }] })).toBe(false);
+    expect(routes({ version: 1, routes: [{ id: "hoja" }] })).toBe(false);
+  });
+
+  it("acepta lo que sí pinta: referencias y textos traducibles", () => {
+    expect(screen(pantalla({ type: "ITText", text: { i18n: "clave" } }))).toBe(true);
+    expect(screen(pantalla({ type: "ITButton", props: { label: { $param: "x" }, size: "sm" } }))).toBe(true);
+  });
+});