@axzydev/axzy_ui_system 1.7.3 → 1.7.4

package/src/showcases/JsonScreenShowcase.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { FaBolt, FaBug, FaCheck, FaTrashAlt } from "react-icons/fa";
 import {
   ITAlert,
@@ -11,8 +11,9 @@ import {
   ITText,
   type JsonEngineIssue,
   type ScreenSchema,
-  parsePartialSchema,
+  type StreamSource,
   axzyCatalogTypes,
+  useSchemaStream,
 } from "../index";
 import { ShowcaseLayout } from "./ShowcaseLayout";
 
@@ -53,7 +54,7 @@ const EJEMPLO: ScreenSchema = {
               props: { title: "Listo para pintar" },
               children: [
                 { type: "ITText", text: "Este árbol viene de un JSON, no de TSX." },
-                { type: "ITProgress", props: { value: 64, max: 100, size: "sm" } },
+                { type: "ITText", props: { muted: true }, text: "Progreso: 64 de 100" },
               ],
             },
           ],
@@ -77,9 +78,17 @@ const EJEMPLO: ScreenSchema = {
 /** Texto inicial del editor: el esquema anterior, formateado. */
 const TEXTO_INICIAL = JSON.stringify(EJEMPLO, null, 2);
 
-/** Velocidad del stream simulado (caracteres por tick). */
+/** Velocidad del stream simulado (caracteres por trozo). */
 const CHUNK = 6;
 
+/** Emite un texto en trozos de `CHUNK` caracteres, con una pausa entre ellos, como haría un modelo. */
+async function* emitir(total: string): AsyncGenerator<string> {
+  for (let cursor = 0; cursor < total.length; cursor += CHUNK) {
+    await new Promise((resolve) => window.setTimeout(resolve, 24));
+    yield total.slice(cursor, cursor + CHUNK);
+  }
+}
+
 /**
  * Laboratorio del motor de pantallas declarativas.
  *
@@ -92,63 +101,40 @@ const CHUNK = 6;
  */
 export const JsonScreenShowcase: React.FC = () => {
   const [texto, setTexto] = useState(TEXTO_INICIAL);
-  const [streaming, setStreaming] = useState(false);
-  const [emitido, setEmitido] = useState(TEXTO_INICIAL.length);
   const [avisos, setAvisos] = useState<JsonEngineIssue[]>([]);
-  const timer = useRef<number | null>(null);
+  /** Fuente del stream simulado. Mientras existe, el laboratorio está emitiendo. */
+  const [fuente, setFuente] = useState<StreamSource | null>(null);
+  const stream = useSchemaStream(fuente);
+  const streaming = fuente !== null;
+  const emitido = stream.text.length;
 
-  /** Estado del esquema: mientras se emite, se parsea en modo tolerante. */
+  /** Estado del esquema: mientras se emite, lo da el hook; si no, se lee el texto del editor. */
   const estado = useMemo(() => {
-    if (!streaming) {
-      try {
-        const completo = JSON.parse(texto) as ScreenSchema;
-        return { tree: completo, status: "complete" as const, pending: 0, roto: false };
-      } catch {
-        return { tree: null, status: "complete" as const, pending: 0, roto: true };
-      }
+    if (streaming) {
+      return { tree: stream.tree, status: stream.status, pending: stream.pendingNodes, roto: stream.broken };
     }
-    const parcial = parsePartialSchema(texto);
-    return {
-      tree: parcial.tree,
-      status: parcial.status,
-      pending: parcial.pendingNodes,
-      roto: parcial.broken,
-    };
-  }, [texto, streaming]);
-
-  /** Detiene el stream y limpia el temporizador. */
-  const detener = useCallback(() => {
-    if (timer.current !== null) {
-      window.clearInterval(timer.current);
-      timer.current = null;
+    try {
+      const completo = JSON.parse(texto) as ScreenSchema;
+      return { tree: completo, status: "complete" as const, pending: 0, roto: false };
+    } catch {
+      return { tree: null, status: "complete" as const, pending: 0, roto: true };
     }
-    setStreaming(false);
-  }, []);
+  }, [texto, streaming, stream]);
 
-  useEffect(() => () => detener(), [detener]);
+  /** Al terminar la emisión, el texto completo pasa al editor y el laboratorio vuelve a ser editable. */
+  useEffect(() => {
+    if (fuente !== null && !stream.streaming && stream.text.length > 0) {
+      setTexto(stream.text);
+      setFuente(null);
+    }
+  }, [fuente, stream.streaming, stream.text]);
 
-  /** Emite el esquema carácter a carácter, como haría un modelo. */
+  /** Emite el esquema por trozos, como haría un modelo. */
   const emitirStream = useCallback(() => {
-    detener();
     setAvisos([]);
-    setEmitido(0);
     setTexto("");
-    setStreaming(true);
-
-    const total = TEXTO_INICIAL;
-    let cursor = 0;
-
-    timer.current = window.setInterval(() => {
-      cursor = Math.min(total.length, cursor + CHUNK);
-      setTexto(total.slice(0, cursor));
-      setEmitido(cursor);
-      if (cursor >= total.length) {
-        window.clearInterval(timer.current as number);
-        timer.current = null;
-        setStreaming(false);
-      }
-    }, 24);
-  }, [detener]);
+    setFuente(emitir(TEXTO_INICIAL));
+  }, []);
 
   /** Registro de acciones del host: el esquema solo puede pedir estos nombres. */
   const resolveAction = useCallback(
@@ -166,6 +152,11 @@ export const JsonScreenShowcase: React.FC = () => {
     );
   }, []);
 
+  /** Los avisos del stream (JR080: falló, o terminó sin cerrar) pasan al panel de avisos. */
+  useEffect(() => {
+    stream.issues.forEach(registrarAviso);
+  }, [stream.issues, registrarAviso]);
+
   const codigo = `<ITSchemaRenderer
   schema={parsePartialSchema(texto).tree}
   onIssue={(issue) => registrar(issue)}
@@ -246,9 +237,8 @@ export const JsonScreenShowcase: React.FC = () => {
                   variant="outlined"
                   color="gray"
                   onClick={() => {
-                    detener();
+                    setFuente(null);
                     setTexto(TEXTO_INICIAL);
-                    setEmitido(TEXTO_INICIAL.length);
                     setAvisos([]);
                   }}
                 />

package/src/showcases/demoApp/demoJson.test.tsx

@@ -0,0 +1,241 @@
+/**
+ * Pruebas de los JSON del demo (`public/demo/app/*.json`).
+ *
+ * Los JSON son contrato con el host: cada acción, slot, fuente, parámetro y clave de
+ * traducción que nombran tiene que existir del lado del host. Estas pruebas lo
+ * comprueban para todas las páginas y para `routes.json`, y renderizan cada página
+ * con el motor exigiendo cero avisos.
+ */
+
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ITSchemaRenderer } from "../../json-renderer/kernel/SchemaRenderer";
+import type { JsonEngineIssue } from "../../json-renderer/shared/errors";
+import type { SlotRegistry } from "../../json-renderer/kernel/slots";
+import { validateSchema, validateRoutes, flattenRoutes, matchRoute, type RoutesSchema } from "../../json-renderer";
+import { sandboxMessages } from "../../sandbox/i18n";
+import { DEMO_ACTIONS, DEMO_SLOT_NAMES } from "../DemoJsonDashboard";
+import { isDemoSource } from "./demoData";
+
+const DIR = join(process.cwd(), "public/demo/app");
+const NO_SON_PAGINAS = ["layout.json", "routes.json"];
+
+/** Lee un JSON del demo. */
+function leer<T = unknown>(nombre: string): T {
+  return JSON.parse(readFileSync(join(DIR, nombre), "utf8")) as T;
+}
+
+/** Recorre todos los objetos de un JSON y llama a `visita` con cada uno. */
+function recorrer(valor: unknown, visita: (objeto: Record<string, unknown>) => void): void {
+  if (Array.isArray(valor)) {
+    valor.forEach((item) => recorrer(item, visita));
+    return;
+  }
+  if (valor && typeof valor === "object") {
+    visita(valor as Record<string, unknown>);
+    Object.values(valor).forEach((item) => recorrer(item, visita));
+  }
+}
+
+/** Todas las claves `{ i18n }` de un JSON. */
+function clavesI18n(json: unknown): string[] {
+  const claves: string[] = [];
+  recorrer(json, (objeto) => {
+    if (typeof objeto.i18n === "string") claves.push(objeto.i18n);
+  });
+  return claves;
+}
+
+/** Todos los nombres de acción (`{ action: "…" }`) de un JSON. */
+function nombresDeAccion(json: unknown): string[] {
+  const nombres: string[] = [];
+  recorrer(json, (objeto) => {
+    if (typeof objeto.action === "string") nombres.push(objeto.action);
+  });
+  return nombres;
+}
+
+/** Todos los `{ $param: "…" }` de un JSON. */
+function parametrosUsados(json: unknown): string[] {
+  const nombres: string[] = [];
+  recorrer(json, (objeto) => {
+    if (typeof objeto.$param === "string") nombres.push(objeto.$param);
+  });
+  return nombres;
+}
+
+/** Nodos `slot` de un JSON, por nombre de slot. */
+function slotsUsados(json: unknown): string[] {
+  const nombres: string[] = [];
+  recorrer(json, (objeto) => {
+    if (objeto.type === "slot" && typeof (objeto.props as { name?: unknown } | undefined)?.name === "string") {
+      nombres.push((objeto.props as { name: string }).name);
+    }
+  });
+  return nombres;
+}
+
+/** Todos los `{ $source: "…" }` de un JSON. */
+function fuentesUsadas(json: unknown): string[] {
+  const nombres: string[] = [];
+  recorrer(json, (objeto) => {
+    if (typeof objeto.$source === "string") nombres.push(objeto.$source);
+  });
+  return nombres;
+}
+
+/** Páginas de pantalla: todos los JSON salvo el shell y las rutas. */
+const PAGINAS = readdirSync(DIR).filter((archivo) => archivo.endsWith(".json") && !NO_SON_PAGINAS.includes(archivo));
+
+const rutas = leer<RoutesSchema>("routes.json");
+const planas = flattenRoutes(rutas.routes);
+
+/** Pantalla que pinta una página, según la ruta que la declara (params a "1"). */
+function ejemploDePagina(pagina: string) {
+  const ruta = planas.find((item) => item.page === pagina);
+  if (!ruta) return null;
+  const segmentos = ruta.segments.map((segmento) => (segmento.startsWith(":") ? "1" : segmento));
+  return matchRoute(planas, segmentos, ruta.query);
+}
+
+/** Diccionario de traducción en español para resolver `{ i18n }` al renderizar. */
+const es = sandboxMessages.es as Record<string, string>;
+const en = sandboxMessages.en as Record<string, string>;
+
+describe("routes.json", () => {
+  it("es un documento de rutas válido", () => {
+    expect(validateRoutes(rutas)).toEqual([]);
+  });
+
+  it("cada ruta hoja pinta una página que existe (docs es la página TSX)", () => {
+    for (const ruta of planas) {
+      if (ruta.page === "docs") continue;
+      expect(existsSync(join(DIR, `${ruta.page}.json`)), `${ruta.id} → ${ruta.page}.json`).toBe(true);
+    }
+  });
+
+  it("no hay páginas huérfanas: cada JSON de pantalla tiene una ruta que lo pinta", () => {
+    const paginasConRuta = new Set(planas.map((ruta) => ruta.page));
+    for (const archivo of PAGINAS) {
+      expect(paginasConRuta.has(archivo.replace(/\.json$/, "")), `${archivo} sin ruta`).toBe(true);
+    }
+  });
+
+  it("los ids de ruta son únicos", () => {
+    const ids = planas.map((ruta) => ruta.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("cada clave de traducción existe en español e inglés", () => {
+    for (const clave of clavesI18n(rutas)) {
+      expect(es[clave], `es: ${clave}`).toBeTruthy();
+      expect(en[clave], `en: ${clave}`).toBeTruthy();
+    }
+  });
+
+  it("cada ruta con :param declara un parámetro que su página usa, y viceversa", () => {
+    for (const ruta of planas) {
+      const declarados = ruta.segments.filter((segmento) => segmento.startsWith(":")).map((segmento) => segmento.slice(1));
+      if (declarados.length === 0 || ruta.page === "docs") continue;
+      const pagina = leer(`${ruta.page}.json`);
+      for (const usado of parametrosUsados(pagina)) {
+        expect(declarados, `${ruta.page} usa $param "${usado}"`).toContain(usado);
+      }
+    }
+  });
+});
+
+describe.each(PAGINAS)("%s", (archivo) => {
+  const pagina = leer(archivo);
+  const nombre = archivo.replace(/\.json$/, "");
+
+  it("es un esquema válido, sin nodos pendientes", () => {
+    const informe = validateSchema(pagina);
+    expect(informe.errors, JSON.stringify(informe.errors)).toHaveLength(0);
+    expect(informe.verdict).toBe("valid");
+    expect(informe.pendingNodes).toBe(0);
+  });
+
+  it("solo usa acciones que el host resuelve", () => {
+    for (const accion of nombresDeAccion(pagina)) {
+      expect(DEMO_ACTIONS as readonly string[], `acción "${accion}"`).toContain(accion);
+    }
+  });
+
+  it("cada clave de traducción existe en español e inglés", () => {
+    for (const clave of clavesI18n(pagina)) {
+      expect(es[clave], `es: ${clave}`).toBeTruthy();
+      expect(en[clave], `en: ${clave}`).toBeTruthy();
+    }
+  });
+
+  it("cada slot nombra un bloque que el host registra", () => {
+    for (const slot of slotsUsados(pagina)) {
+      expect(DEMO_SLOT_NAMES, `slot "${slot}"`).toContain(slot);
+    }
+  });
+
+  it("cada $source usa una fuente declarada en `data`, con un handler que existe", () => {
+    const data = ((pagina as { data?: Record<string, { handler: string }> }).data ?? {}) as Record<string, { handler: string }>;
+    for (const fuente of fuentesUsadas(pagina)) {
+      expect(data[fuente], `fuente "${fuente}" sin declarar en data`).toBeTruthy();
+      expect(isDemoSource(data[fuente].handler), `handler "${data[fuente].handler}"`).toBe(true);
+    }
+  });
+
+  it("cada $param tiene una ruta que lo proporciona", () => {
+    const ejemplo = ejemploDePagina(nombre);
+    if (parametrosUsados(pagina).length === 0) return;
+    expect(ejemplo, `${nombre} necesita una ruta con :param`).not.toBeNull();
+    for (const usado of parametrosUsados(pagina)) {
+      expect(ejemplo?.params, `$param "${usado}"`).toHaveProperty(usado);
+    }
+  });
+
+  it("se pinta con el motor sin avisos (ni errores ni advertencias)", () => {
+    const issues: JsonEngineIssue[] = [];
+    const ejemplo = ejemploDePagina(nombre);
+    const slots: SlotRegistry = Object.fromEntries(
+      DEMO_SLOT_NAMES.map((nombreSlot) => [nombreSlot, () => <div data-slot={nombreSlot} />])
+    );
+
+    render(
+      <ITSchemaRenderer
+        schema={pagina as never}
+        params={ejemplo?.params ?? {}}
+        // Como el host real: todos los efectos del demo están implementados.
+        effects={{ toast: () => undefined, navigate: () => undefined, refresh: () => undefined, openOverlay: () => undefined, closeOverlay: () => undefined }}
+        // Como el host real: solo las acciones de DEMO_ACTIONS tienen handler.
+        resolveAction={(_node, _prop, accion) => {
+          const nombre = (accion as { action?: unknown } | null)?.action;
+          return typeof nombre === "string" && (DEMO_ACTIONS as readonly string[]).includes(nombre) ? () => undefined : undefined;
+        }}
+        slots={slots}
+        dataHandlers={{
+          usuarios: async () => ({ data: [], total: 0 }),
+          pedidos: async () => ({ data: [], total: 0 }),
+          productos: async () => ({ data: [], total: 0 }),
+        }}
+        resolveValue={(valor) =>
+          valor && typeof valor === "object" && typeof (valor as { i18n?: unknown }).i18n === "string"
+            ? es[(valor as { i18n: string }).i18n]
+            : valor
+        }
+        onIssue={(issue) => issues.push(issue)}
+      />
+    );
+
+    expect(issues.map((issue) => `${issue.code} ${issue.path}: ${issue.message}`)).toEqual([]);
+  });
+});
+
+describe("layout.json", () => {
+  it("declara la marca y nada más: el menú sale de routes.json", () => {
+    const layout = leer<{ layout: { brand?: { text?: string }; modules?: unknown } }>("layout.json");
+    expect(layout.layout.brand?.text).toBeTruthy();
+    expect(layout.layout.modules).toBeUndefined();
+  });
+});

package/src/showcases/demoApp/routes.test.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { buildNavigationTree, flattenRoutes, matchRoute, routeHref, validateRoutes, type NavNode, type RoutesSchema } from "../../json-renderer";
+import { sandboxMessages } from "../../sandbox/i18n";
+
+const DIR = join(process.cwd(), "public/demo/app");
+const rutas = JSON.parse(readFileSync(join(DIR, "routes.json"), "utf8")) as RoutesSchema;
+const planas = flattenRoutes(rutas.routes);
+
+/** Todas las claves `{ i18n }` de un árbol de navegación. */
+function claves(nodos: NavNode[]): string[] {
+  return nodos.flatMap((nodo) => [
+    ...(typeof nodo.label === "object" && nodo.label !== null && "i18n" in nodo.label ? [String(nodo.label.i18n)] : []),
+    ...(nodo.children ? claves(nodo.children) : []),
+  ]);
+}
+
+describe("routes.json del demo", () => {
+  it("es un documento de rutas válido", () => {
+    expect(validateRoutes(rutas)).toEqual([]);
+  });
+
+  it("cada página de una hoja tiene su JSON (docs es la página TSX)", () => {
+    for (const ruta of planas) {
+      if (ruta.page === "docs") continue;
+      expect(existsSync(join(DIR, `${ruta.page}.json`)), `${ruta.id} → ${ruta.page}.json`).toBe(true);
+    }
+  });
+
+  it("todas las etiquetas del menú tienen traducción en el catálogo del sandbox", () => {
+    for (const clave of claves(buildNavigationTree(rutas.routes))) {
+      expect(sandboxMessages.es[clave], clave).toBeTruthy();
+    }
+  });
+
+  it("el menú sale de las rutas: grupos con sus sub-items y la marca de pedidos", () => {
+    const arbol = buildNavigationTree(rutas.routes);
+    expect(arbol.map((entrada) => entrada.id)).toEqual(["inicio", "usuarios", "pedidos", "productos", "reportes", "docs"]);
+    expect(arbol.find((entrada) => entrada.id === "pedidos")?.badge).toBe(11);
+    expect(arbol.find((entrada) => entrada.id === "usuarios")?.children?.map((hijo) => hijo.href)).toEqual([
+      "/usuarios",
+      "/usuarios?estado=Activo",
+      "/usuarios?estado=Inactivo",
+    ]);
+  });
+
+  it("cada dirección del menú casa con la ruta que la declara", () => {
+    for (const ruta of planas) {
+      const casada = matchRoute(planas, ruta.segments, ruta.query);
+      expect(casada?.route.id, routeHref(ruta)).toBe(ruta.id);
+    }
+  });
+
+  it("la ruta de detalle recibe el id como :param y no compite con /usuarios", () => {
+    expect(matchRoute(planas, ["usuarios", "7"])).toMatchObject({ route: { id: "usuario-detalle" }, params: { id: "7" } });
+    expect(matchRoute(planas, ["usuarios"])?.route.id).toBe("u-todos");
+  });
+
+  it("una query sin ruta específica cae en la ruta base del mismo path", () => {
+    expect(matchRoute(planas, ["pedidos"], { estado: "Cancelado" })?.route.id).toBe("p-todos");
+  });
+});

package/src/showcases/demoApp/schemas.test.ts

@@ -10,7 +10,9 @@ function leerJson(nombre: string): unknown {
   return JSON.parse(readFileSync(join(DIR, nombre), "utf8"));
 }
 
-const paginas = readdirSync(DIR).filter((archivo) => archivo.endsWith(".json") && archivo !== "layout.json");
+// layout.json (marca) y routes.json (rutas) no son pantallas: se prueban aparte.
+const NO_SON_PAGINAS = ["layout.json", "routes.json"];
+const paginas = readdirSync(DIR).filter((archivo) => archivo.endsWith(".json") && !NO_SON_PAGINAS.includes(archivo));
 
 describe("JSON del demo", () => {
   it("hay páginas y un layout", () => {
@@ -25,23 +27,10 @@ describe("JSON del demo", () => {
     expect(informe.pendingNodes).toBe(0);
   });
 
-  it("el layout declara marca, módulos y páginas existentes", () => {
-    const layout = leerJson("layout.json") as {
-      layout: { brand?: { text?: string }; modules: { id: string; page: string; icon?: string }[] };
-    };
+  it("el layout declara la marca; el menú vive en routes.json", () => {
+    const layout = leerJson("layout.json") as { layout: { brand?: { text?: string }; modules?: unknown } };
     expect(layout.layout.brand?.text).toBeTruthy();
-    expect(layout.layout.modules.length).toBeGreaterThanOrEqual(6);
-    for (const modulo of layout.layout.modules) {
-      expect(modulo.id, "cada módulo necesita id").toBeTruthy();
-      expect(modulo.page, `${modulo.id} necesita page`).toBeTruthy();
-    }
-    // Todo módulo apunta a una página que existe (docs no tiene archivo propio).
-    const ids = new Set(layout.layout.modules.map((modulo) => modulo.page));
-    expect(ids.has("docs")).toBe(true);
-    for (const pagina of ids) {
-      if (pagina === "docs") continue;
-      expect(paginas, `falta ${pagina}.json`).toContain(`${pagina}.json`);
-    }
+    expect(layout.layout.modules, "los módulos ya no van en layout.json").toBeUndefined();
   });
 
   it("las páginas declaran título y descripción traducibles", () => {