@axzydev/axzy_ui_system 1.7.0 → 1.7.1

package/src/showcases/JsonScreenShowcase.tsx

@@ -0,0 +1,341 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { FaBolt, FaBug, FaCheck, FaTrashAlt } from "react-icons/fa";
+import {
+  ITAlert,
+  ITBadget,
+  ITButton,
+  ITCard,
+  ITFlex,
+  ITJSONEditor,
+  ITSchemaRenderer,
+  ITText,
+  type JsonEngineIssue,
+  type ScreenSchema,
+  parsePartialSchema,
+  axzyCatalogTypes,
+} from "../index";
+import { ShowcaseLayout } from "./ShowcaseLayout";
+
+/** Esquema de ejemplo: usa el catálogo real y muestra permisos y estado. */
+const EJEMPLO: ScreenSchema = {
+  version: 1,
+  id: "laboratorio",
+  title: "Pantalla de ejemplo",
+  content: [
+    {
+      type: "ITFlex",
+      props: { align: "center", justify: "between", wrap: "wrap", gap: 3 },
+      children: [
+        {
+          type: "ITFlex",
+          props: { align: "center", gap: 2 },
+          children: [
+            { type: "ITBadget", props: { label: "Motor", color: "primary" } },
+            { type: "ITText", props: { muted: true }, text: "Esquema interpretado en vivo" },
+          ],
+        },
+        {
+          type: "ITButton",
+          props: { label: "Acción declarada", color: "primary", size: "sm", onClick: { action: "saludar" } },
+        },
+      ],
+    },
+    {
+      type: "ITGrid",
+      props: { container: true, spacing: 3 },
+      children: [
+        {
+          type: "ITGrid",
+          props: { item: true, md: 6 },
+          children: [
+            {
+              type: "ITCard",
+              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: "ITGrid",
+          props: { item: true, md: 6 },
+          children: [
+            {
+              type: "ITAlert",
+              props: { variant: "info", title: "Casos cubiertos" },
+              children: [{ type: "ITText", text: "Si algo no está en el catálogo, se avisa y no se pinta." }],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+/** Texto inicial del editor: el esquema anterior, formateado. */
+const TEXTO_INICIAL = JSON.stringify(EJEMPLO, null, 2);
+
+/** Velocidad del stream simulado (caracteres por tick). */
+const CHUNK = 6;
+
+/**
+ * Laboratorio del motor de pantallas declarativas.
+ *
+ * Izquierda: el esquema en `ITJSONEditor`. Derecha: lo que pinta el motor. El
+ * botón «emitir como stream» escribe el esquema carácter a carácter para ver el
+ * render progresivo y comprobar que lo pendiente no se pinta a medias.
+ *
+ * @example
+ * // Ruta del sandbox: #ui-system/feedback/jsonscreen
+ */
+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);
+
+  /** Estado del esquema: mientras se emite, se parsea en modo tolerante. */
+  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 };
+      }
+    }
+    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;
+    }
+    setStreaming(false);
+  }, []);
+
+  useEffect(() => () => detener(), [detener]);
+
+  /** Emite el esquema carácter a carácter, 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]);
+
+  /** Registro de acciones del host: el esquema solo puede pedir estos nombres. */
+  const resolveAction = useCallback(
+    () => () => {
+      window.alert("Acción declarada ejecutada por el host.");
+    },
+    []
+  );
+
+  const registrarAviso = useCallback((issue: JsonEngineIssue) => {
+    setAvisos((previos) =>
+      previos.some((item) => item.code === issue.code && item.path === issue.path)
+        ? previos
+        : [...previos, issue].slice(-8)
+    );
+  }, []);
+
+  const codigo = `<ITSchemaRenderer
+  schema={parsePartialSchema(texto).tree}
+  onIssue={(issue) => registrar(issue)}
+  resolveAction={() => actions[accion]}
+  pendingFallback={<ITSkeleton />}
+/>`;
+
+  return (
+    <ShowcaseLayout
+      title="Motor de pantallas"
+      description="ITSchemaRenderer interpreta un esquema JSON contra un catálogo de componentes con lista blanca. Pinta mientras el esquema llega por trozos, avisa con código y ruta, y aísla los nodos que fallan."
+      demo={
+        <div className="grid w-full gap-4 xl:grid-cols-[minmax(0,380px)_minmax(0,1fr)]">
+          <div className="min-w-0">
+            <ITCard title="Esquema (JSON)">
+              <ITJSONEditor value={texto} onChange={setTexto} height={420} readOnly={streaming} />
+            </ITCard>
+          </div>
+          <div className="min-w-0">
+            <ITCard title="Pantalla resultante">
+              <div className="min-h-[420px]">
+                {estado.roto && !estado.tree ? (
+                  <ITAlert variant="error" title="El esquema no es JSON válido">
+                    Corrige el texto de la izquierda para volver a pintar.
+                  </ITAlert>
+                ) : (
+                  <ITSchemaRenderer
+                    schema={estado.tree}
+                    onIssue={registrarAviso}
+                    resolveAction={resolveAction}
+                    pendingFallback={<ITText muted>·</ITText>}
+                  />
+                )}
+              </div>
+
+              <ITFlex align="center" gap={2} wrap="wrap" className="mt-4 border-t border-slate-200 pt-3 dark:border-slate-800">
+                <ITButton
+                  label={streaming ? "Emitiendo…" : "Emitir como stream"}
+                  icon={<FaBolt size={10} />}
+                  size="sm"
+                  color="primary"
+                  onClick={emitirStream}
+                  disabled={streaming}
+                />
+                <ITButton
+                  label="Documentación del motor"
+                  icon={<FaBolt size={10} />}
+                  size="sm"
+                  variant="text"
+                  color="gray"
+                  onClick={() => {
+                    window.location.hash = "#demo/app/docs";
+                  }}
+                />
+                <ITButton
+                  label="Ver panel (sistema completo)"
+                  icon={<FaBolt size={10} />}
+                  size="sm"
+                  color="primary"
+                  onClick={() => {
+                    window.location.hash = "#demo/app/inicio";
+                  }}
+                />
+                <ITButton
+                  label="Ver portafolio de demo"
+                  icon={<FaBolt size={10} />}
+                  size="sm"
+                  variant="outlined"
+                  color="gray"
+                  onClick={() => {
+                    window.location.hash = "#demo";
+                  }}
+                />
+                <ITButton
+                  label="Reiniciar"
+                  icon={<FaTrashAlt size={10} />}
+                  size="sm"
+                  variant="outlined"
+                  color="gray"
+                  onClick={() => {
+                    detener();
+                    setTexto(TEXTO_INICIAL);
+                    setEmitido(TEXTO_INICIAL.length);
+                    setAvisos([]);
+                  }}
+                />
+                <ITText
+                  as="span"
+                  className="font-mono !text-[10px] uppercase !tracking-[0.12em]"
+                  muted
+                >
+                  {streaming
+                    ? `stream ${emitido}/${TEXTO_INICIAL.length} · ${estado.pending} nodos pendientes`
+                    : `esquema completo · ${axzyCatalogTypes.length} tipos en el catálogo`}
+                </ITText>
+              </ITFlex>
+
+              {avisos.length > 0 && (
+                <div className="mt-3 space-y-1.5">
+                  <ITFlex align="center" gap={1.5}>
+                    <FaBug size={10} className="text-amber-500" />
+                    <ITText
+                      as="span"
+                      className="font-mono !text-[10px] uppercase !tracking-[0.12em]"
+                      muted
+                    >
+                      Avisos del motor
+                    </ITText>
+                  </ITFlex>
+                  {avisos.map((aviso) => (
+                    <ITFlex
+                      key={`${aviso.code}-${aviso.path}`}
+                      align="start"
+                      gap={2}
+                      className="rounded-[6px] border border-slate-200 px-2 py-1.5 dark:border-slate-800"
+                    >
+                      <ITBadget
+                        label={aviso.code}
+                        color={aviso.severity === "error" ? "danger" : "warning"}
+                        size="sm"
+                      />
+                      <div className="min-w-0">
+                        <p className="text-[11px] leading-snug text-slate-700 dark:text-slate-300">{aviso.message}</p>
+                        <p className="font-mono text-[10px] text-slate-500 dark:text-slate-400">{aviso.path || "raíz"}</p>
+                      </div>
+                    </ITFlex>
+                  ))}
+                </div>
+              )}
+
+              {!streaming && avisos.length === 0 && (
+                <ITFlex align="center" gap={1.5} className="mt-3">
+                  <FaCheck size={10} className="text-emerald-500" />
+                  <ITText as="span" className="font-mono !text-[10px] uppercase !tracking-[0.12em]" muted>
+                    Sin avisos: el esquema cabe entero en el catálogo
+                  </ITText>
+                </ITFlex>
+              )}
+            </ITCard>
+          </div>
+        </div>
+      }
+      code={codigo}
+      doc={{
+        summary: "Ejecuta un esquema JSON contra el catálogo de componentes, con lista blanca y avisos.",
+        description:
+          "El esquema se trata como entrada no confiable: un tipo fuera del catálogo no rompe la pantalla, una prop prohibida se ignora con aviso y un componente que lanza queda aislado. Durante el stream, los nodos pendientes no se pintan a medias.",
+        examples: [
+          '<ITSchemaRenderer schema={{ version: 1, id: "demo", content: { type: "ITText", text: "Hola" } }} />',
+          '<ITSchemaRenderer schema={parsePartialSchema(tokens).tree} pendingFallback={<ITSkeleton />} />',
+          '<ITSchemaRenderer schema={schema} onIssue={(issue) => console.warn(issue.code, issue.path)} />',
+        ],
+        props: [
+          { name: "schema", type: "ScreenSchema | null", required: true, description: "Esquema de pantalla; admite árbol parcial." },
+          { name: "catalog", type: "Catalog", default: "axzyCatalog", description: "Componentes y props permitidos." },
+          { name: "limits", type: "Partial<EngineLimits>", default: "—", description: "Presupuesto de nodos, profundidad y tiempos." },
+          { name: "resolveValue", type: "(value, path) => unknown", default: "—", description: "Resuelve referencias ($state, $param…)." },
+          { name: "resolveAction", type: "(node, prop, action, path) => fn", default: "—", description: "Traduce acciones declaradas a handlers del host." },
+          { name: "pendingFallback", type: "ReactNode", default: "—", description: "Qué pintar mientras un nodo está pendiente." },
+          { name: "onIssue", type: "(issue) => void", default: "—", description: "Avisos con código y ruta." },
+          { name: "className", type: "string", default: "—", description: "Clases del contenedor raíz." },
+        ],
+        notes: [
+          `El catálogo de esta fase expone ${axzyCatalogTypes.length} tipos con lista blanca de props.`,
+          "Códigos de aviso: JR010 tipo fuera del catálogo · JR011 prop ignorada · JR012 nodo aislado · JR013 presupuesto excedido.",
+          "Pulsa «Emitir como stream» para ver el render progresivo: lo pendiente no se pinta a medias.",
+        ],
+      }}
+    />
+  );
+};
+
+export default JsonScreenShowcase;

package/src/showcases/demoApp/demoData.ts

@@ -0,0 +1,181 @@
+/**
+ * Datos simulados del dashboard de demostración.
+ *
+ * Hace el papel del backend: el motor **nunca** hace red, así que el host expone
+ * un `fetcher` por nombre de fuente (`usuarios`, `pedidos`) y el esquema solo
+ * escribe `{ "$source": "usuarios" }`. Es exactamente el contrato de la fase 4:
+ * el esquema nombra, el host resuelve.
+ */
+
+import type { ITDataTableFetchParams, ITDataTableResponse } from "../../index";
+
+/** Un usuario del sistema. */
+export interface DemoUsuario extends Record<string, unknown> {
+  id: number;
+  nombre: string;
+  correo: string;
+  rol: string;
+  estado: string;
+  alta: string;
+  edad: number;
+  empresa: string;
+  turno: string;
+}
+
+/** Un pedido del sistema. */
+export interface DemoPedido extends Record<string, unknown> {
+  folio: string;
+  cliente: string;
+  total: number;
+  estado: string;
+  fecha: string;
+}
+
+/** Fuentes disponibles, por nombre. */
+export type DemoSource = "usuarios" | "pedidos" | "productos";
+
+/** Usuarios de ejemplo. */
+export const USUARIOS: DemoUsuario[] = [
+  "Ana Ruiz", "Luis Paredes", "Marcela Ortiz", "Jorge Cano", "Sofía Lara",
+  "Diego Núñez", "Paula Ferrer", "Iván Robles", "Nora Salas", "Emilio Tapia",
+  "Clara Vidal", "Hugo Medina", "Rita Campos", "Abel Cordero", "Lucía Ponce",
+  "Mateo Barrios", "Elena Ríos", "Tomás Ávila", "Inés Lozano", "Bruno Cárdenas",
+  "Alba Solís", "Ciro Mena", "Dora Ibáñez", "Fabián Correa", "Gala Nieves",
+].map((nombre, index) => ({
+  id: index + 1,
+  nombre,
+  correo: `${nombre.toLowerCase().replace(/[^a-z]+/g, ".")}@axzy.dev`,
+  rol: ["Admin", "Operador", "Auditor", "Soporte"][index % 4],
+  estado: index % 7 === 0 ? "Inactivo" : "Activo",
+  alta: `2026-0${(index % 9) + 1}-${String((index % 27) + 1).padStart(2, "0")}`,
+  edad: 22 + (index % 30),
+  empresa: ["CYC ERP", "Puerto Nuevo", "CheckApp", "Grupo Delta", "Nova Salud"][index % 5],
+  turno: ["08:00", "09:30", "14:00", "22:00"][index % 4],
+}));
+
+const CLIENTES = ["CYC ERP", "Puerto Nuevo", "CheckApp", "Grupo Delta", "Nova Salud", "Ferretería Sur"];
+const ESTADOS = ["Pagado", "Pendiente", "Enviado", "Cancelado"];
+
+/** Pedidos de ejemplo. */
+export const PEDIDOS: DemoPedido[] = Array.from({ length: 42 }, (_, index) => ({
+  folio: `PED-${String(1042 + index).padStart(4, "0")}`,
+  cliente: CLIENTES[index % CLIENTES.length],
+  total: Math.round((180 + ((index * 137) % 2400)) * 100) / 100,
+  estado: ESTADOS[index % ESTADOS.length],
+  fecha: `2026-${String((index % 9) + 1).padStart(2, "0")}-${String((index % 27) + 1).padStart(2, "0")}`,
+}));
+
+/** Borrador de usuario que envía el formulario del host. */
+export interface DemoUsuarioInput {
+  nombre: string;
+  correo: string;
+  rol: string;
+  estado: string;
+  edad: number;
+  empresa: string;
+  turno: string;
+  alta: string;
+}
+
+/** Crea un usuario y devuelve su id. */
+export function crearUsuario(input: DemoUsuarioInput): number {
+  const id = USUARIOS.reduce((max, usuario) => Math.max(max, usuario.id), 0) + 1;
+  USUARIOS.unshift({ id, ...input, alta: new Date().toISOString().slice(0, 10) });
+  return id;
+}
+
+/** Actualiza un usuario por id. */
+export function actualizarUsuario(id: number, input: DemoUsuarioInput): void {
+  const indice = USUARIOS.findIndex((usuario) => usuario.id === id);
+  if (indice >= 0) USUARIOS[indice] = { ...USUARIOS[indice], ...input };
+}
+
+/** Elimina un usuario por id. */
+export function eliminarUsuario(id: number): void {
+  const indice = USUARIOS.findIndex((usuario) => usuario.id === id);
+  if (indice >= 0) USUARIOS.splice(indice, 1);
+}
+
+/** Busca un usuario por id. */
+export function obtenerUsuario(id: number): DemoUsuario | undefined {
+  return USUARIOS.find((usuario) => usuario.id === id);
+}
+
+/** Productos de ejemplo. */
+export const PRODUCTOS_DEMO = [
+  ["AX-1001", "Teclado mecánico", 1290, 24, "Periféricos"],
+  ["AX-1002", "Monitor 27\"", 6890, 8, "Pantallas"],
+  ["AX-1003", "Mouse inalámbrico", 590, 61, "Periféricos"],
+  ["AX-1004", "Docking station", 2450, 12, "Conectividad"],
+  ["AX-1005", "Webcam 4K", 1890, 0, "Video"],
+  ["AX-1006", "Audífonos", 990, 37, "Audio"],
+  ["AX-1007", "Hub USB-C", 790, 44, "Conectividad"],
+  ["AX-1008", "Silla ergonómica", 5490, 5, "Mobiliario"],
+  ["AX-1009", "Escritorio eléctrico", 8990, 3, "Mobiliario"],
+  ["AX-1010", "Lámpara de escritorio", 690, 28, "Iluminación"],
+  ["AX-1011", "Base para laptop", 450, 52, "Accesorios"],
+  ["AX-1012", "Cable HDMI 2.1", 320, 90, "Cables"],
+].map(([sku, nombre, precio, stock, categoria]) => ({ sku, nombre, precio, stock, categoria }));
+
+/** Colecciones por fuente. */
+const COLECCIONES: Record<DemoSource, Record<string, unknown>[]> = {
+  usuarios: USUARIOS as unknown as Record<string, unknown>[],
+  pedidos: PEDIDOS as unknown as Record<string, unknown>[],
+  productos: PRODUCTOS_DEMO as unknown as Record<string, unknown>[],
+};
+
+/** `true` cuando el nombre es una fuente registrada. */
+export function isDemoSource(name: string): name is DemoSource {
+  return name in COLECCIONES;
+}
+
+/** Filtro de estado activo (lo escribe el host). */
+let estadoFiltro: string | null = null;
+
+/** Fija el filtro de estado global; `null`/`Todos` lo desactiva. */
+export function setEstadoFiltro(estado: string | null): void {
+  estadoFiltro = estado && estado !== "Todos" ? estado : null;
+}
+
+/** Compara dos valores para ordenar. */
+function compare(a: unknown, b: unknown): number {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b), "es");
+}
+
+/**
+ * Crea el `fetchData` de una fuente: aplica filtros, orden y paginación.
+ *
+ * El retardo simula la red para que se vean los estados de carga del motor.
+ *
+ * @example
+ * const fetcher = createDemoFetcher("usuarios");
+ * await fetcher({ page: 1, limit: 5, filters: {} });
+ */
+export function createDemoFetcher(source: DemoSource) {
+  return async (params: ITDataTableFetchParams): Promise<ITDataTableResponse<Record<string, unknown>>> => {
+    // Latencia simulada: hace visible el estado de carga de la tabla.
+    await new Promise((resolve) => setTimeout(resolve, 260));
+
+    let rows = [...COLECCIONES[source]];
+
+    // Filtros por columna: igualdad para catálogo, subcadena para texto.
+    for (const [key, value] of Object.entries(params.filters ?? {})) {
+      if (value === undefined || value === null || value === "") continue;
+      const needle = String(value).toLowerCase();
+      rows = rows.filter((row) => String(row[key] ?? "").toLowerCase().includes(needle));
+    }
+
+    // Filtro triple del host (persistido en la URL).
+    if (estadoFiltro) rows = rows.filter((row) => String(row.estado ?? "") === estadoFiltro);
+
+    if (params.sort) {
+      const { key, direction } = params.sort;
+      rows.sort((a, b) => (direction === "asc" ? compare(a[key], b[key]) : compare(b[key], a[key])));
+    }
+
+    const total = rows.length;
+    const start = (params.page - 1) * params.limit;
+    return { data: rows.slice(start, start + params.limit), total };
+  };
+}

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

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { leerNodo, listarNodos } from "./nodeTree";
+
+const esquema = {
+  version: 1,
+  id: "demo",
+  content: [
+    { type: "ITStack", id: "raiz", children: [
+      { type: "ITText", text: "hola" },
+      { type: "ITButton", id: "cta", props: { label: "Ir" } },
+      { type: "ITCard", children: [{ type: "ITChip", props: { label: "x" } }] },
+    ] },
+  ],
+};
+
+describe("inspector de nodos", () => {
+  it("lista los nodos con su ruta numérica", () => {
+    const nodos = listarNodos(esquema);
+    expect(nodos.map((n) => n.tipo)).toEqual(["ITStack", "ITText", "ITButton", "ITCard", "ITChip"]);
+    expect(nodos[2].ruta).toEqual([0, 1]);
+    expect(nodos[2].etiqueta).toContain("#cta");
+  });
+
+  it("devuelve el subárbol de una ruta", () => {
+    expect(leerNodo(esquema, [0, 2])).toMatchObject({ type: "ITCard" });
+    expect(leerNodo(esquema, [0, 1])).toMatchObject({ type: "ITButton", id: "cta" });
+  });
+
+  it("la ruta vacía es el esquema completo", () => {
+    expect(leerNodo(esquema, [])).toBe(esquema);
+  });
+
+  it("corta la lista a 40 nodos y sobrevive a basura", () => {
+    const grande = { content: Array.from({ length: 60 }, () => ({ type: "ITText", text: "x" })) };
+    expect(listarNodos(grande)).toHaveLength(40);
+    expect(listarNodos(null)).toEqual([]);
+    expect(leerNodo(esquema, [9, 9])).toBeUndefined();
+  });
+});

package/src/showcases/demoApp/nodeTree.ts

@@ -0,0 +1,35 @@
+/** Helpers del inspector de nodos de la documentación (puros y testeables). */
+
+/** Un nodo seleccionable del árbol, con su ruta numérica. */
+interface NodoRuta {
+  ruta: number[];
+  etiqueta: string;
+  tipo: string;
+}
+
+/** Recorre el árbol y lista los nodos seleccionables (hasta 40). */
+export function listarNodos(nodo: unknown, ruta: number[] = [], salida: NodoRuta[] = []): NodoRuta[] {
+  if (!nodo || typeof nodo !== "object" || salida.length >= 40) return salida;
+  const objeto = nodo as { type?: string; id?: string; children?: unknown; content?: unknown };
+  if (typeof objeto.type === "string") {
+    salida.push({
+      ruta,
+      tipo: objeto.type,
+      etiqueta: `${objeto.type}${objeto.id ? ` #${objeto.id}` : ""} · ${ruta.join(".")}`,
+    });
+  }
+  const hijos = objeto.children ?? objeto.content;
+  const lista = Array.isArray(hijos) ? hijos : hijos ? [hijos] : [];
+  lista.forEach((hijo, indice) => listarNodos(hijo, [...ruta, indice], salida));
+  return salida;
+}
+
+/** Devuelve el subárbol de una ruta numérica. */
+export function leerNodo(nodo: unknown, ruta: number[]): unknown {
+  return ruta.reduce((actual: unknown, indice) => {
+    const objeto = actual as { children?: unknown; content?: unknown } | null;
+    const hijos = objeto?.children ?? objeto?.content;
+    const lista = Array.isArray(hijos) ? hijos : hijos ? [hijos] : [];
+    return lista[indice];
+  }, nodo);
+}

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

@@ -0,0 +1,54 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { validateSchema } from "../../json-renderer/validation/validate";
+
+const DIR = join(process.cwd(), "public/demo/app");
+
+/** Lee y parsea un archivo del demo. */
+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");
+
+describe("JSON del demo", () => {
+  it("hay páginas y un layout", () => {
+    expect(paginas.length).toBeGreaterThanOrEqual(5);
+    expect(() => leerJson("layout.json")).not.toThrow();
+  });
+
+  it.each(paginas)("%s es un esquema válido", (archivo) => {
+    const informe = validateSchema(leerJson(archivo));
+    expect(informe.errors, JSON.stringify(informe.errors)).toHaveLength(0);
+    expect(informe.verdict).toBe("valid");
+    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 }[] };
+    };
+    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`);
+    }
+  });
+
+  it("las páginas declaran título y descripción traducibles", () => {
+    for (const archivo of paginas) {
+      const esquema = leerJson(archivo) as { title?: { i18n?: string }; description?: { i18n?: string } };
+      expect(esquema.title?.i18n, `${archivo} sin title.i18n`).toBeTruthy();
+      expect(esquema.description?.i18n, `${archivo} sin description.i18n`).toBeTruthy();
+    }
+  });
+});