@axzydev/axzy_ui_system 1.7.3 → 1.8.0

package/src/json-renderer/actions/effects.test.tsx

@@ -0,0 +1,115 @@
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen as testingScreen } from "@testing-library/react";
+import { ITSchemaRenderer } from "../kernel/SchemaRenderer";
+import type { JsonEngineIssue } from "../shared/errors";
+import type { NodeSchema, ScreenSchema } from "../kernel/types";
+import { wrapAction, type EffectContext, type EffectRegistry } from "./effects";
+
+/** Contexto de pruebas: traducción literal y avisos acumulados. */
+function contexto(effects?: EffectRegistry) {
+  const avisos: JsonEngineIssue[] = [];
+  const context: EffectContext = {
+    effects,
+    path: ["content", 0],
+    resolveText: (value) => (typeof value === "string" ? value : ""),
+    report: (aviso) => avisos.push(aviso),
+  };
+  return { context, avisos };
+}
+
+describe("wrapAction", () => {
+  it("sin then ni onError devuelve el handler tal cual", () => {
+    const handler = () => "ok";
+    const { context } = contexto({});
+    expect(wrapAction(handler, { action: "x" }, context)).toBe(handler);
+    expect(wrapAction(handler, undefined, context)).toBe(handler);
+  });
+
+  it("then se ejecuta después de un handler que termina bien", () => {
+    const orden: string[] = [];
+    const toast = vi.fn(() => orden.push("toast"));
+    const handler = vi.fn(() => orden.push("handler"));
+    const { context } = contexto({ toast });
+
+    const envuelto = wrapAction(handler, { action: "x", then: [{ toast: { variant: "success", message: "Hecho" } }] }, context);
+    envuelto("args");
+
+    expect(orden).toEqual(["handler", "toast"]);
+    expect(toast).toHaveBeenCalledWith({ variant: "success", message: "Hecho" });
+  });
+
+  it("los efectos sueltos de la acción cuentan como un then más", () => {
+    const navigate = vi.fn();
+    const { context } = contexto({ navigate });
+    wrapAction(() => undefined, { action: "x", navigate: "/inicio" }, context)();
+    expect(navigate).toHaveBeenCalledWith("/inicio");
+  });
+
+  it("onError se ejecuta, y then no, cuando el handler lanza", () => {
+    const toast = vi.fn();
+    const { context } = contexto({ toast });
+    const envuelto = wrapAction(
+      () => {
+        throw new Error("fallo");
+      },
+      { action: "x", then: [{ toast: { message: "Bien" } }], onError: { toast: { variant: "error", message: "Mal" } } },
+      context
+    );
+    envuelto();
+    expect(toast).toHaveBeenCalledTimes(1);
+    expect(toast).toHaveBeenCalledWith({ variant: "error", message: "Mal" });
+  });
+
+  it("con un handler asíncrono espera la promesa: then si resuelve, onError si rechaza", async () => {
+    const toast = vi.fn();
+    const { context } = contexto({ toast });
+    const acciones = { action: "x", then: [{ toast: { message: "Bien" } }], onError: { toast: { variant: "error", message: "Mal" } } };
+
+    await wrapAction(() => Promise.resolve("ok"), acciones, context)();
+    expect(toast).toHaveBeenLastCalledWith({ variant: "info", message: "Bien" });
+
+    await (wrapAction(() => Promise.reject(new Error("x")), acciones, context)() as Promise<unknown>).catch(() => undefined);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(toast).toHaveBeenLastCalledWith({ variant: "error", message: "Mal" });
+  });
+
+  it("un efecto que el host no implementa avisa con JR040 al pintar, y no rompe al ejecutar", () => {
+    const { context, avisos } = contexto({});
+    const envuelto = wrapAction(() => undefined, { action: "x", then: [{ toast: { message: "Hola" } }] }, context);
+    expect(avisos[0]).toMatchObject({ code: "JR040", severity: "warning" });
+    expect(() => envuelto()).not.toThrow();
+  });
+});
+
+describe("efectos en pantalla", () => {
+  const pantalla = (action: Record<string, unknown>): ScreenSchema =>
+    ({
+      version: 1,
+      id: "efectos",
+      content: { type: "ITButton", props: { label: "Enviar", onClick: action } } as NodeSchema,
+    }) as ScreenSchema;
+
+  it("al pulsar, el host recibe la acción y después se ejecuta el toast del JSON", () => {
+    const orden: string[] = [];
+    const host = vi.fn(() => orden.push("host"));
+    const toast = vi.fn(() => orden.push("toast"));
+
+    render(
+      <ITSchemaRenderer
+        schema={pantalla({ action: "guardar", then: [{ toast: { variant: "success", message: { i18n: "k" } } }] })}
+        resolveAction={(_node, _prop, action) => {
+          const nombre = (action as { action?: string }).action;
+          return nombre === "guardar" ? host : undefined;
+        }}
+        resolveValue={(value) => (value && typeof value === "object" && "i18n" in value ? "Guardado" : value)}
+        effects={{ toast }}
+      />
+    );
+
+    fireEvent.click(testingScreen.getByRole("button", { name: "Enviar" }));
+
+    expect(orden).toEqual(["host", "toast"]);
+    expect(toast).toHaveBeenCalledWith({ variant: "success", message: "Guardado" });
+  });
+});

package/src/json-renderer/actions/effects.ts

@@ -0,0 +1,291 @@
+/**
+ * Efectos de acción: lo que el esquema pide que pase después de una acción.
+ *
+ * Una acción declara su efecto en el JSON; el host decide cómo se cumple. El motor:
+ *
+ * - ejecuta el handler del host (la acción en sí);
+ * - si termina bien, aplica `then` (y los efectos sueltos de la acción);
+ * - si falla o rechaza, aplica `onError`.
+ *
+ * Los efectos (`toast`, `navigate`, `refresh`, `openOverlay`, `closeOverlay`) los
+ * cumple el registro `effects` que pasa el host. Un efecto también puede ser otra
+ * acción (`{ action, args, then, onError }`): el motor la resuelve con el handler del
+ * host y aplica sus propios efectos. Como el JSON es finito, el encadenado termina;
+ * `MAX_EFFECT_DEPTH` lo limita de todos modos (`JR042`).
+ *
+ * Los textos y rutas pueden leer el resultado del handler con `{ "$result": "campo" }`
+ * o `{campo}` dentro de una dirección.
+ *
+ * Si el esquema pide un efecto que el host no implementa, o una acción encadenada que
+ * no existe, el motor avisa al pintar (`JR040`), nunca al ejecutar.
+ *
+ * Sin `then`, `onError` ni efectos, el handler se devuelve tal cual: no cambia nada.
+ */
+
+import { issue, type JsonEngineIssue } from "../shared/errors";
+import { formatPath, type SchemaPath } from "../shared/paths";
+import type { EffectSchema } from "../kernel/types";
+
+/** Profundidad máxima de acciones encadenadas desde efectos. */
+export const MAX_EFFECT_DEPTH = 5;
+
+/** Variante de un aviso (`toast`). */
+export type ToastVariant = "success" | "error" | "info" | "warning";
+
+/** Lo que el host implementa. Cada efecto es opcional: el motor avisa si falta uno que se usa. */
+export interface EffectRegistry {
+  /** Muestra un aviso al usuario. */
+  toast?: (aviso: { variant: ToastVariant; message: string }) => void;
+  /** Navega a una dirección. */
+  navigate?: (href: string) => void;
+  /** Refresca una fuente de datos. */
+  refresh?: (source: string) => void;
+  /** Abre un overlay declarado. */
+  openOverlay?: (name: string) => void;
+  /** Cierra un overlay; sin nombre, el que esté abierto. */
+  closeOverlay?: (name?: string) => void;
+}
+
+/** Contexto que necesita un efecto para ejecutarse en un nodo concreto. */
+export interface EffectContext {
+  /** Registro que implementa el host. */
+  effects?: EffectRegistry;
+  /** Traduce un valor del esquema (por ejemplo, `{ i18n }`) a texto. */
+  resolveText: (value: unknown, path: SchemaPath) => string;
+  /** Recibe los avisos del render (`JR040`, `JR042`). */
+  report: (aviso: JsonEngineIssue) => void;
+  /** Ruta del nodo, para los avisos. */
+  path: SchemaPath;
+  /** Handler del host para una acción encadenada por nombre, o `undefined` si no existe. */
+  resolveChained?: (name: string) => ((...args: unknown[]) => unknown) | undefined;
+  /** Profundidad de encadenado. La acción del nodo es 0. */
+  depth?: number;
+  /** Milisegundos que una promesa del host puede tardar antes de considerarla colgada (`JR041`). */
+  timeoutMs?: number;
+  /** Recibe los avisos que se producen después del render (un timeout, por ejemplo). */
+  reportRuntime?: (aviso: JsonEngineIssue) => void;
+  /** Escribe en el estado de la pantalla (efecto `set`). */
+  setState?: (cambios: Record<string, unknown>) => void;
+  /** Resuelve referencias del esquema (`$state`, `$param`…) de un valor. */
+  resolveRaw?: (value: unknown, path: SchemaPath) => unknown;
+}
+
+/** Un paso que se ejecuta cuando la acción termina, con el resultado del handler. */
+type Paso = (resultado: unknown) => void;
+
+/** Nombres de efecto que el motor conoce. */
+const EFFECT_KEYS = ["toast", "navigate", "refresh", "openOverlay", "closeOverlay", "set"] as const;
+
+/** Efectos que cumple el host. `set` lo cumple el propio motor, así que no se pide al registro. */
+const EFFECT_KEYS_DEL_HOST = ["toast", "navigate", "refresh", "openOverlay", "closeOverlay"] as const;
+
+/** Forma de una acción con efectos, tal como la escribe el JSON. */
+interface ActionWithEffects extends EffectSchema {
+  /** Efectos que se ejecutan si la acción termina bien. */
+  then?: EffectSchema[];
+  /** Efecto que se ejecuta si la acción falla. */
+  onError?: EffectSchema;
+}
+
+/** Lee un campo del resultado por ruta (`"usuario.id"`). Sin resultado o sin campo, `undefined`. */
+function leerResultado(ruta: string, resultado: unknown): unknown {
+  return ruta.split(".").reduce<unknown>(
+    (actual, clave) => (actual && typeof actual === "object" ? (actual as Record<string, unknown>)[clave] : undefined),
+    resultado
+  );
+}
+
+/** Sustituye las referencias `{ $result }` de un valor por el dato real del handler. */
+function resolverResultado(valor: unknown, resultado: unknown): unknown {
+  if (!valor || typeof valor !== "object" || Array.isArray(valor)) return valor;
+  const objeto = valor as Record<string, unknown>;
+  if (typeof objeto.$result === "string") return leerResultado(objeto.$result, resultado) ?? "";
+  if (objeto.params && typeof objeto.params === "object") {
+    const params = Object.fromEntries(
+      Object.entries(objeto.params as Record<string, unknown>).map(([clave, valorParam]) => [
+        clave,
+        resolverResultado(valorParam, resultado),
+      ])
+    );
+    return { ...objeto, params };
+  }
+  return valor;
+}
+
+/** Sustituye `{campo}` en una dirección por el campo del resultado. */
+function plantilla(texto: string, resultado: unknown): string {
+  return texto.replace(/\{([\w.]+)\}/g, (_, ruta: string) => {
+    const valor = leerResultado(ruta, resultado);
+    return valor === undefined ? "" : String(valor);
+  });
+}
+
+/** Efectos sueltos de una acción (sin `action`, `args`, `then` ni `onError`), o `null` si no tiene. */
+function efectosSueltos(declarada: ActionWithEffects): EffectSchema | null {
+  const sueltos: Record<string, unknown> = {};
+  for (const clave of EFFECT_KEYS) {
+    if (declarada[clave] !== undefined) sueltos[clave] = declarada[clave];
+  }
+  return Object.keys(sueltos).length > 0 ? (sueltos as EffectSchema) : null;
+}
+
+/** Avisa de los efectos de registro que el esquema pide y el host no implementa. Se llama al pintar. */
+function comprobarRegistro(efecto: EffectSchema, context: EffectContext): void {
+  for (const clave of EFFECT_KEYS_DEL_HOST) {
+    if (efecto[clave] === undefined) continue;
+    if (typeof context.effects?.[clave] !== "function") {
+      context.report(
+        issue("JR040", `El host no implementa el efecto \`${clave}\`.`, formatPath(context.path), {
+          severity: "warning",
+          hint: "Regístralo en `effects` del renderizador o quita el efecto del esquema.",
+        })
+      );
+    }
+  }
+}
+
+/** Cumple un efecto de registro con el resultado del handler. */
+function cumplirEfecto(efecto: EffectSchema, context: EffectContext, resultado: unknown): void {
+  // `set` lo cumple el motor: escribe en el estado de la pantalla, con el resultado ya aplicado.
+  if (efecto.set && context.setState) {
+    const cambios: Record<string, unknown> = {};
+    for (const [clave, valor] of Object.entries(efecto.set)) {
+      const conResultado = resolverResultado(valor, resultado);
+      cambios[clave] = context.resolveRaw ? context.resolveRaw(conResultado, context.path) : conResultado;
+    }
+    context.setState(cambios);
+  }
+
+  const registro = context.effects;
+  if (!registro) return;
+
+  if (efecto.toast && registro.toast) {
+    registro.toast({
+      variant: efecto.toast.variant ?? "info",
+      message: context.resolveText(resolverResultado(efecto.toast.message, resultado), context.path),
+    });
+  }
+  if (typeof efecto.navigate === "string" && registro.navigate) {
+    registro.navigate(plantilla(efecto.navigate, resultado));
+  }
+  if (typeof efecto.refresh === "string" && registro.refresh) registro.refresh(efecto.refresh);
+  if (typeof efecto.openOverlay === "string" && registro.openOverlay) registro.openOverlay(efecto.openOverlay);
+  if (efecto.closeOverlay !== undefined && registro.closeOverlay) {
+    registro.closeOverlay(typeof efecto.closeOverlay === "string" ? efecto.closeOverlay : undefined);
+  }
+}
+
+/**
+ * Convierte cada efecto en un paso. Los efectos de registro se comprueban aquí; una
+ * acción encadenada se resuelve aquí y se envuelve con sus propios efectos.
+ */
+function pasosDe(efectos: EffectSchema[], context: EffectContext): Paso[] {
+  const profundidad = context.depth ?? 0;
+
+  return efectos.map((efecto): Paso => {
+    if (typeof efecto.action !== "string") {
+      comprobarRegistro(efecto, context);
+      return (resultado) => cumplirEfecto(efecto, context, resultado);
+    }
+
+    if (profundidad + 1 > MAX_EFFECT_DEPTH) {
+      context.report(
+        issue("JR042", `El encadenado de acciones supera ${MAX_EFFECT_DEPTH} niveles.`, formatPath(context.path), {
+          severity: "error",
+          hint: "Reduce los `then` anidados.",
+        })
+      );
+      return () => undefined;
+    }
+
+    const handler = context.resolveChained?.(efecto.action);
+    if (!handler) {
+      context.report(
+        issue("JR040", `La acción encadenada \`${efecto.action}\` no está registrada por el host.`, formatPath(context.path), {
+          severity: "error",
+          hint: "Regístrala en las acciones del renderizador o cambia el nombre en el esquema.",
+        })
+      );
+      return () => undefined;
+    }
+
+    const encadenada = wrapAction(handler, efecto, { ...context, depth: profundidad + 1 });
+    return () => encadenada(efecto.args);
+  });
+}
+
+/**
+ * Envuelve el handler de una acción para que cumpla sus efectos.
+ *
+ * Los efectos sueltos de la acción cuentan como un `then` más, delante de la lista.
+ *
+ * @example
+ * const handler = wrapAction(hostHandler, { action: "enviar", then: [{ toast: { message: "Hecho" } }] }, context);
+ */
+export function wrapAction(
+  handler: (...args: unknown[]) => unknown,
+  action: unknown,
+  context: EffectContext
+): (...args: unknown[]) => unknown {
+  if (!action || typeof action !== "object") return handler;
+  const declarada = action as ActionWithEffects;
+  const sueltos = efectosSueltos(declarada);
+  const alTerminar: EffectSchema[] = [...(sueltos ? [sueltos] : []), ...(Array.isArray(declarada.then) ? declarada.then : [])];
+  const alFallar = declarada.onError;
+
+  if (alTerminar.length === 0 && !alFallar) return handler;
+
+  const pasosOk = pasosDe(alTerminar, context);
+  const pasoError = alFallar ? pasosDe([alFallar], context)[0] : undefined;
+  const aplicar = (resultado: unknown) => pasosOk.forEach((paso) => paso(resultado));
+
+  return (...args: unknown[]) => {
+    let resultado: unknown;
+    try {
+      resultado = handler(...args);
+    } catch {
+      pasoError?.(undefined);
+      return undefined;
+    }
+
+    if (resultado && typeof (resultado as PromiseLike<unknown>).then === "function") {
+      // Una promesa que no resuelve a tiempo cuenta como fallo: se aplica onError y el
+      // resultado tardío se ignora. Así una acción colgada no deja el botón esperando.
+      let resuelta = false;
+      const limite = context.timeoutMs;
+      const temporizador =
+        limite !== undefined && Number.isFinite(limite)
+          ? setTimeout(() => {
+              if (resuelta) return;
+              resuelta = true;
+              context.reportRuntime?.(
+                issue("JR041", `La acción excedió ${limite} ms y se considera fallida.`, formatPath(context.path), {
+                  severity: "error",
+                  hint: "El host debe responder o rechazar la acción a tiempo.",
+                })
+              );
+              pasoError?.(undefined);
+            }, limite)
+          : undefined;
+
+      (resultado as Promise<unknown>).then(
+        (valor) => {
+          if (resuelta) return;
+          resuelta = true;
+          clearTimeout(temporizador);
+          aplicar(valor);
+        },
+        () => {
+          if (resuelta) return;
+          resuelta = true;
+          clearTimeout(temporizador);
+          pasoError?.(undefined);
+        }
+      );
+      return resultado;
+    }
+
+    aplicar(resultado);
+    return resultado;
+  };
+}

package/src/json-renderer/actions/effectsChain.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from "vitest";
+import type { JsonEngineIssue } from "../shared/errors";
+import { MAX_EFFECT_DEPTH, wrapAction, type EffectContext, type EffectRegistry } from "./effects";
+
+/** Contexto de pruebas: traduce textos a cadena y acumula avisos. */
+function contexto(overrides: Partial<EffectContext> = {}) {
+  const avisos: JsonEngineIssue[] = [];
+  const context: EffectContext = {
+    path: ["content", 0],
+    resolveText: (value) => (typeof value === "string" ? value : JSON.stringify(value)),
+    report: (aviso) => avisos.push(aviso),
+    ...overrides,
+  };
+  return { context, avisos };
+}
+
+describe("acciones encadenadas desde un efecto", () => {
+  it("un efecto con action llama al handler del host con sus args", () => {
+    const otra = vi.fn();
+    const { context } = contexto({ resolveChained: (nombre) => (nombre === "otra" ? otra : undefined) });
+
+    wrapAction(() => undefined, { action: "guardar", then: [{ action: "otra", args: { id: 7 } }] }, context)();
+
+    expect(otra).toHaveBeenCalledWith({ id: 7 });
+  });
+
+  it("la acción encadenada aplica sus propios efectos al terminar", () => {
+    const toast = vi.fn();
+    const otra = vi.fn();
+    const registro: EffectRegistry = { toast };
+    const { context } = contexto({
+      effects: registro,
+      resolveChained: (nombre) => (nombre === "otra" ? otra : undefined),
+    });
+
+    wrapAction(
+      () => undefined,
+      { action: "guardar", then: [{ action: "otra", then: [{ toast: { variant: "success", message: "Encadenado" } }] }] },
+      context
+    )();
+
+    expect(otra).toHaveBeenCalledTimes(1);
+    expect(toast).toHaveBeenCalledWith({ variant: "success", message: "Encadenado" });
+  });
+
+  it("una acción encadenada que el host no registró avisa con JR040 al pintar", () => {
+    const { context, avisos } = contexto({ resolveChained: () => undefined });
+    wrapAction(() => undefined, { action: "guardar", then: [{ action: "no-existe" }] }, context);
+    expect(avisos[0]).toMatchObject({ code: "JR040", severity: "error" });
+  });
+
+  it("el encadenado tiene un límite: más de MAX_EFFECT_DEPTH niveles avisa con JR042", () => {
+    const { context, avisos } = contexto({ resolveChained: () => () => undefined });
+
+    // Anidamos MAX_EFFECT_DEPTH + 2 acciones: la última supera el límite.
+    let efecto: Record<string, unknown> = { action: "hoja" };
+    for (let nivel = 0; nivel < MAX_EFFECT_DEPTH + 2; nivel += 1) {
+      efecto = { action: "nivel", then: [efecto] };
+    }
+    wrapAction(() => undefined, { action: "inicio", then: [efecto] }, context);
+
+    expect(avisos.some((aviso) => aviso.code === "JR042")).toBe(true);
+  });
+
+  it("un encadenado dentro del límite no avisa", () => {
+    const { context, avisos } = contexto({ resolveChained: () => () => undefined });
+    wrapAction(() => undefined, { action: "a", then: [{ action: "b", then: [{ action: "c" }] }] }, context);
+    expect(avisos.filter((aviso) => aviso.code === "JR042")).toHaveLength(0);
+  });
+});
+
+describe("datos del resultado en los efectos", () => {
+  it("un parámetro { $result } de i18n toma el dato que devolvió el handler", () => {
+    const toast = vi.fn();
+    const { context } = contexto({ effects: { toast } });
+
+    wrapAction(
+      () => ({ folio: "PED-1042" }),
+      { action: "crear", then: [{ toast: { message: { i18n: "pedido.creado", params: { folio: { $result: "folio" } } } } }] },
+      context
+    )();
+
+    expect(toast).toHaveBeenCalledTimes(1);
+    expect(toast.mock.calls[0][0].message).toContain("PED-1042");
+  });
+
+  it("navigate sustituye {campo} por el dato del resultado", () => {
+    const navigate = vi.fn();
+    const { context } = contexto({ effects: { navigate } });
+
+    wrapAction(() => ({ id: 7 }), { action: "crear", then: [{ navigate: "/usuarios/{id}" }] }, context)();
+
+    expect(navigate).toHaveBeenCalledWith("/usuarios/7");
+  });
+
+  it("con un handler asíncrono, los efectos reciben el valor resuelto", async () => {
+    const navigate = vi.fn();
+    const { context } = contexto({ effects: { navigate } });
+
+    await wrapAction(
+      () => Promise.resolve({ id: 9 }),
+      { action: "crear", then: [{ navigate: "/usuarios/{id}" }] },
+      context
+    )();
+
+    expect(navigate).toHaveBeenCalledWith("/usuarios/9");
+  });
+
+  it("un campo que el resultado no trae llega vacío, sin romper", () => {
+    const toast = vi.fn();
+    const { context } = contexto({ effects: { toast } });
+
+    wrapAction(() => ({}), { action: "crear", then: [{ toast: { message: { $result: "no.existe" } } }] }, context)();
+
+    expect(toast).toHaveBeenCalledWith({ variant: "info", message: "" });
+  });
+});