@axzydev/axzy_ui_system 1.7.3 → 1.8.0

package/src/json-renderer/binding/binding.test.tsx

@@ -0,0 +1,168 @@
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen as testingScreen } from "@testing-library/react";
+import { ITSchemaRenderer } from "../kernel/SchemaRenderer";
+import type { ScreenSchema } from "../kernel/types";
+import type { JsonEngineIssue } from "../shared/errors";
+import { createBindingResolver, type BindingScope, type DataLoader } from "./resolveValue";
+
+/** Resolutor con avisos acumulados, para leerlos en cada prueba. */
+function setup(scope: Partial<BindingScope> = {}) {
+  const avisos: JsonEngineIssue[] = [];
+  const resolve = createBindingResolver({ report: (aviso) => avisos.push(aviso), ...scope });
+  return { resolve, avisos };
+}
+
+describe("$source", () => {
+  it("devuelve un loader que no llama al handler hasta que el componente lo invoca", async () => {
+    const handler = vi.fn(async (query: unknown) => ({ data: [], total: 0, query }));
+    const { resolve, avisos } = setup({
+      data: { usuarios: { handler: "usuarios" } },
+      handlers: { usuarios: handler },
+    });
+
+    const loader = resolve({ $source: "usuarios" }, ["content", 0]) as DataLoader;
+    expect(typeof loader).toBe("function");
+    expect(handler).not.toHaveBeenCalled();
+
+    const respuesta = await loader({ page: 2 });
+    expect(handler).toHaveBeenCalledWith({ page: 2 }, {});
+    expect(respuesta).toMatchObject({ total: 0, query: { page: 2 } });
+    expect(avisos).toHaveLength(0);
+  });
+
+  it("resuelve los parámetros declarados con $state y $param antes de llamar al handler", async () => {
+    const handler = vi.fn(() => []);
+    const { resolve } = setup({
+      data: { pedidos: { handler: "pedidos", params: { estado: { $state: "estado" }, empresa: { $param: "empresa" }, limite: 5 } } },
+      state: { estado: "Pendiente" },
+      params: { empresa: "CheckApp" },
+      handlers: { pedidos: handler },
+    });
+
+    await (resolve({ $source: "pedidos" }, ["content", 0]) as DataLoader)();
+    expect(handler).toHaveBeenCalledWith(undefined, { estado: "Pendiente", empresa: "CheckApp", limite: 5 });
+  });
+
+  it("una fuente no declarada avisa con JR030 y su carga rechaza sin lanzar al resolver", async () => {
+    const { resolve, avisos } = setup({ data: {}, handlers: {} });
+
+    const loader = resolve({ $source: "pedidos" }, ["content", 1]) as DataLoader;
+    expect(avisos).toHaveLength(1);
+    expect(avisos[0]).toMatchObject({ code: "JR030", severity: "error" });
+    await expect(loader()).rejects.toThrow(/no está declarada en `data`/);
+  });
+
+  it("un handler que el host no registró avisa con JR030 y rechaza la carga", async () => {
+    const { resolve, avisos } = setup({ data: { usuarios: { handler: "usuarios" } }, handlers: {} });
+
+    const loader = resolve({ $source: "usuarios" }, ["content", 0]) as DataLoader;
+    expect(avisos[0]).toMatchObject({ code: "JR030" });
+    await expect(loader()).rejects.toThrow(/no está registrado por el host/);
+  });
+
+  it("un handler que lanza se convierte en rechazo de la carga, no en error del render", async () => {
+    const { resolve, avisos } = setup({
+      data: { usuarios: { handler: "usuarios" } },
+      handlers: {
+        usuarios: () => {
+          throw new Error("fallo del host");
+        },
+      },
+    });
+
+    const loader = resolve({ $source: "usuarios" }, ["content", 0]) as DataLoader;
+    await expect(loader()).rejects.toThrow("fallo del host");
+    expect(avisos).toHaveLength(0);
+  });
+
+  it("un $source usado como parámetro avisa con JR032 y no se resuelve", async () => {
+    const handler = vi.fn(() => []);
+    const { resolve, avisos } = setup({
+      data: { usuarios: { handler: "usuarios", params: { origen: { $source: "pedidos" } } } },
+      handlers: { usuarios: handler },
+    });
+
+    await (resolve({ $source: "usuarios" }, ["content", 0]) as DataLoader)();
+    expect(handler).toHaveBeenCalledWith(undefined, {});
+    expect(avisos[0]).toMatchObject({ code: "JR032" });
+  });
+});
+
+describe("$state y $param", () => {
+  it("$state lee el estado inicial de la pantalla", () => {
+    const { resolve, avisos } = setup({ state: { titulo: "Hola" } });
+    expect(resolve({ $state: "titulo" }, ["content", 0])).toBe("Hola");
+    expect(avisos).toHaveLength(0);
+  });
+
+  it("$state sin valor avisa con JR032 y devuelve undefined", () => {
+    const { resolve, avisos } = setup({ state: {} });
+    expect(resolve({ $state: "titulo" }, ["content", 0])).toBeUndefined();
+    expect(avisos[0]).toMatchObject({ code: "JR032", severity: "warning" });
+  });
+
+  it("$param lee el valor que pone el host, no el esquema", () => {
+    const { resolve } = setup({ params: { id: "42" } });
+    expect(resolve({ $param: "id" }, ["content", 0])).toBe("42");
+  });
+
+  it("$param sin valor avisa con JR032", () => {
+    const { resolve, avisos } = setup({ params: {} });
+    expect(resolve({ $param: "id" }, ["content", 0])).toBeUndefined();
+    expect(avisos[0]).toMatchObject({ code: "JR032" });
+  });
+
+  it("no hereda claves de la cadena de prototipos", () => {
+    const { resolve, avisos } = setup({ state: {} });
+    expect(resolve({ $state: "toString" }, ["content", 0])).toBeUndefined();
+    expect(avisos[0]).toMatchObject({ code: "JR032" });
+  });
+});
+
+describe("operadores no soportados y valores del host", () => {
+  it("un operador de otra fase (`$row`) avisa con JR032 y no llega a la prop", () => {
+    const { resolve, avisos } = setup();
+    expect(resolve({ $row: "nombre" }, ["content", 0])).toBeUndefined();
+    expect(avisos[0]).toMatchObject({ code: "JR032", severity: "warning" });
+  });
+
+  it("los textos `{ i18n }` y los literales pasan al host", () => {
+    const host = vi.fn((value: unknown) => ({ host: value }));
+    const { resolve, avisos } = setup({ host });
+
+    expect(resolve({ i18n: "sandbox.app.back" }, ["content", 0])).toEqual({ host: { i18n: "sandbox.app.back" } });
+    expect(resolve("Hola", ["content", 0])).toEqual({ host: "Hola" });
+    expect(host).toHaveBeenCalledTimes(2);
+    expect(avisos).toHaveLength(0);
+  });
+
+  it("sin host, los valores que no son referencias se devuelven tal cual", () => {
+    const { resolve } = setup();
+    expect(resolve(3, ["content", 0])).toBe(3);
+  });
+});
+
+describe("ITSchemaRenderer con binding", () => {
+  const pantalla = (estado: Partial<ScreenSchema>, content: unknown): ScreenSchema =>
+    ({ version: 1, id: "binding", content, ...estado }) as ScreenSchema;
+
+  it("pinta un $state declarado en la pantalla", () => {
+    render(
+      <ITSchemaRenderer
+        schema={pantalla({ state: { titulo: "Estado de pantalla" } }, { type: "ITText", text: { $state: "titulo" } })}
+      />
+    );
+    expect(testingScreen.getByText("Estado de pantalla")).toBeTruthy();
+  });
+
+  it("pinta un $param que llega por la prop `params`", () => {
+    render(
+      <ITSchemaRenderer
+        schema={pantalla({}, { type: "ITText", text: { $param: "nombre" } })}
+        params={{ nombre: "Ruta con parámetro" }}
+      />
+    );
+    expect(testingScreen.getByText("Ruta con parámetro")).toBeTruthy();
+  });
+});

package/src/json-renderer/binding/resolveValue.ts

@@ -0,0 +1,193 @@
+/**
+ * Binding mínimo del motor: resuelve las referencias declarativas del esquema
+ * (`$source`, `$state`, `$param`) antes de pintar cada prop.
+ *
+ * Solo lee y nunca hace red. Una fuente es un **loader**: el componente lo invoca
+ * cuando necesita datos (una tabla, al paginar o filtrar) y la función que lo
+ * atiende es un `handler` que registra el host por nombre. El esquema no puede
+ * nombrar una URL ni un endpoint.
+ *
+ * Escribir estado llega con las acciones (fase 5); `$row` y `$form` llegan con las
+ * tablas y los formularios (fase 8). Hasta entonces avisan con `JR032`.
+ */
+
+import { issue, type JsonEngineIssue } from "../shared/errors";
+import { formatPath, type SchemaPath } from "../shared/paths";
+import type { DataSourceSchema, SchemaValue } from "../kernel/types";
+
+/**
+ * Handler que registra el host. Recibe la query que pide el componente (por ejemplo,
+ * página y filtros de una tabla) y los parámetros declarados en la fuente.
+ */
+export type DataHandler = (query: unknown, params: Record<string, SchemaValue>) => unknown;
+
+/** Función de carga que recibe el componente. Siempre devuelve una promesa. */
+export type DataLoader = (query?: unknown) => Promise<unknown>;
+
+/** Lo que el binding necesita del esquema, del host y del render en curso. */
+export interface BindingScope {
+  /** Fuentes declaradas por la pantalla (`ScreenSchema.data`). */
+  data?: Record<string, DataSourceSchema>;
+  /** Estado inicial de la pantalla (`ScreenSchema.state`). */
+  state?: Record<string, SchemaValue>;
+  /** Parámetros de la ruta, aportados por el host (`$param`). */
+  params?: Record<string, SchemaValue>;
+  /** Handlers que registra el host, por nombre. */
+  handlers?: Record<string, DataHandler>;
+  /** Recibe los avisos del binding (`JR030`, `JR032`). */
+  report: (aviso: JsonEngineIssue) => void;
+  /** Resuelve el resto de valores (por ejemplo, textos `{ i18n }`). Lo aporta el host. */
+  host?: (value: unknown, path: SchemaPath) => unknown;
+}
+
+/** Resolutor de valores que consume el kernel al pintar cada prop. */
+export type BindingResolver = (value: unknown, path: SchemaPath) => unknown;
+
+/** Claves que una fuente no puede declarar: cualquiera de ellas sería una petición de red. */
+const CLAVES_DE_RED = ["url", "endpoint", "href", "src"];
+
+/** Operadores que el binding mínimo sabe resolver. */
+const SUPPORTED_REFERENCES = ["$source", "$state", "$param"] as const;
+
+/** `true` cuando la clave existe en el objeto (sin heredar de la cadena de prototipos). */
+function own(record: object | undefined, key: string): boolean {
+  return record !== undefined && Object.prototype.hasOwnProperty.call(record, key);
+}
+
+/** `true` cuando el valor es un objeto con alguna clave que empieza por `$`. */
+function isDollarReference(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.keys(value).some((key) => key.startsWith("$"));
+}
+
+/** Aviso de referencia sin valor o no soportada. */
+function referenceIssue(message: string, path: SchemaPath, hint: string): JsonEngineIssue {
+  return issue("JR032", message, formatPath(path), { severity: "warning", hint });
+}
+
+/**
+ * Crea el resolutor de valores de una pantalla.
+ *
+ * Las referencias se resuelven aquí; el resto de valores pasa al `host`. Los
+ * loaders de fuente no llaman a ningún handler hasta que el componente los invoca.
+ *
+ * @example
+ * const resolve = createBindingResolver({
+ *   data: { usuarios: { handler: "usuarios" } },
+ *   handlers: { usuarios: (query) => fetchUsuarios(query) },
+ *   report: (aviso) => issues.push(aviso),
+ * });
+ * resolve({ $source: "usuarios" }, ["content", 0]); // loader (no se llama aún)
+ */
+export function createBindingResolver(scope: BindingScope): BindingResolver {
+  /** Lee `$state` o `$param`. Si no hay valor, avisa y devuelve `undefined`. */
+  const readValue = (
+    table: Record<string, SchemaValue> | undefined,
+    kind: "$state" | "$param",
+    key: string,
+    path: SchemaPath
+  ): SchemaValue | undefined => {
+    if (own(table, key)) return table![key];
+    scope.report(
+      referenceIssue(
+        `La referencia \`${kind}: "${key}"\` no tiene valor.`,
+        path,
+        kind === "$state" ? "Declara el valor en `state` del esquema." : "El host debe pasar el parámetro en `params`."
+      )
+    );
+    return undefined;
+  };
+
+  /** Resuelve los parámetros de una fuente. Solo admite valores y `$state`/`$param`. */
+  const resolveParams = (declared: Record<string, SchemaValue> | undefined, path: SchemaPath) => {
+    const resolved: Record<string, SchemaValue> = {};
+    for (const [name, raw] of Object.entries(declared ?? {})) {
+      if (!isDollarReference(raw)) {
+        resolved[name] = raw;
+        continue;
+      }
+      const [key] = Object.keys(raw).filter((candidate) => candidate.startsWith("$"));
+      if (key === "$state" && typeof raw[key] === "string") {
+        const value = readValue(scope.state, "$state", raw[key] as string, path);
+        if (value !== undefined) resolved[name] = value;
+      } else if (key === "$param" && typeof raw[key] === "string") {
+        const value = readValue(scope.params, "$param", raw[key] as string, path);
+        if (value !== undefined) resolved[name] = value;
+      } else {
+        scope.report(
+          referenceIssue(
+            "Un parámetro de fuente solo admite valores, `$state` o `$param`.",
+            path,
+            "Las fuentes no se encadenan: declara la fuente sin referencias a otras fuentes."
+          )
+        );
+      }
+    }
+    return resolved;
+  };
+
+  /** Loader que falla de forma controlada: avisa con `JR030` y rechaza la carga. */
+  const failingLoader = (message: string, path: SchemaPath, hint: string): DataLoader => {
+    scope.report(issue("JR030", message, formatPath(path), { severity: "error", hint }));
+    return () => Promise.reject(new Error(message));
+  };
+
+  /** Crea el loader de una fuente declarada. No invoca el handler todavía. */
+  const sourceLoader = (name: string, path: SchemaPath): DataLoader => {
+    if (!own(scope.data, name)) {
+      return failingLoader(
+        `La fuente \`${name}\` no está declarada en \`data\`.`,
+        path,
+        "Declárala en `data` del esquema con el `handler` que registra el host."
+      );
+    }
+    const declared = scope.data![name];
+    // Una fuente nunca pide red: si el esquema intenta declarar una URL, se rechaza y se avisa.
+    const claveDeRed = Object.keys(declared).find((clave) => CLAVES_DE_RED.includes(clave));
+    if (claveDeRed) {
+      scope.report(
+        issue("JR031", `El esquema declara \`${claveDeRed}\` en la fuente "${name}": las fuentes no pueden pedir red.`, formatPath(path), {
+          severity: "error",
+          hint: "Una fuente solo nombra un `handler` que registra el host.",
+        })
+      );
+      return () => Promise.reject(new Error(`La fuente "${name}" no puede pedir red.`));
+    }
+    const handler = own(scope.handlers, declared.handler) ? scope.handlers![declared.handler] : undefined;
+    if (typeof handler !== "function") {
+      return failingLoader(
+        `El handler \`${declared.handler}\` no está registrado por el host.`,
+        path,
+        "El host debe registrarlo en `dataHandlers` del renderizador."
+      );
+    }
+    const params = resolveParams(declared.params, path);
+    // Dentro de la promesa: un handler que lanza se convierte en rechazo, no en error del render.
+    return (query) => new Promise((resolve) => resolve(handler(query, params)));
+  };
+
+  /** Resuelve una referencia `$…` de una prop. Operadores no soportados avisan. */
+  const resolveReference = (ref: Record<string, unknown>, path: SchemaPath): unknown => {
+    const keys = Object.keys(ref).filter((key) => key.startsWith("$"));
+    const [key] = keys;
+    if (keys.length !== 1 || !(SUPPORTED_REFERENCES as readonly string[]).includes(key) || typeof ref[key] !== "string") {
+      scope.report(
+        referenceIssue(
+          `Referencia no soportada: ${keys.join(", ") || "sin operador"}.`,
+          path,
+          "Soportadas: `$source`, `$state` y `$param`. Los demás operadores llegan con las acciones y las tablas."
+        )
+      );
+      return undefined;
+    }
+    const name = ref[key] as string;
+    if (key === "$source") return sourceLoader(name, path);
+    if (key === "$state") return readValue(scope.state, "$state", name, path);
+    return readValue(scope.params, "$param", name, path);
+  };
+
+  return (value, path) => {
+    if (isDollarReference(value)) return resolveReference(value, path);
+    return scope.host ? scope.host(value, path) : value;
+  };
+}

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

@@ -91,6 +91,11 @@ export const AXZY_CATALOG_ENTRIES: CatalogEntry[] = [
     summary: "Tarjeta con título, imagen y contenido.",
     props: {
       title: { kind: "string" },
+      tone: {
+        kind: "enum",
+        values: ["primary", "secondary", "ternary", "success", "info", "warning", "danger"],
+        doc: "Tinte pastel de la tarjeta (token --color-<tone>-soft).",
+      },
       image: { kind: "string", doc: "URL de la imagen de cabecera." },
       alt: { kind: "string" },
       onClick: { kind: "action" },

package/src/json-renderer/estado-acciones.test.tsx

@@ -0,0 +1,166 @@
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen as testingScreen, waitFor } from "@testing-library/react";
+import { ITSchemaRenderer } from "./kernel/SchemaRenderer";
+import type { JsonEngineIssue } from "./shared/errors";
+import type { NodeSchema, ScreenSchema } from "./kernel/types";
+
+/** Esquema mínimo con el contenido indicado y un estado inicial opcional. */
+const pantalla = (content: unknown, state?: Record<string, unknown>): ScreenSchema =>
+  ({ version: 1, id: "estado", content, ...(state ? { state } : {}) }) as ScreenSchema;
+
+/** Acumula los avisos del renderizador. */
+function avisos() {
+  const lista: JsonEngineIssue[] = [];
+  return { lista, onIssue: (aviso: JsonEngineIssue) => lista.push(aviso) };
+}
+
+describe("efecto set: escribir en el estado de la pantalla", () => {
+  it("un botón escribe un valor y el texto que lo lee se actualiza", () => {
+    render(
+      <ITSchemaRenderer
+        schema={pantalla(
+          [
+            { type: "ITText", text: { $state: "titulo" } },
+            {
+              type: "ITButton",
+              props: { label: "Cambiar", onClick: { action: "cambiar", then: [{ set: { titulo: "Nuevo" } }] } },
+            } as NodeSchema,
+          ],
+          { titulo: "Inicial" }
+        )}
+        resolveAction={() => () => undefined}
+      />
+    );
+    expect(testingScreen.getByText("Inicial")).toBeTruthy();
+
+    fireEvent.click(testingScreen.getByRole("button", { name: "Cambiar" }));
+
+    expect(testingScreen.getByText("Nuevo")).toBeTruthy();
+    expect(testingScreen.queryByText("Inicial")).toBeNull();
+  });
+
+  it("set puede tomar un dato del resultado del handler con $result", () => {
+    render(
+      <ITSchemaRenderer
+        schema={pantalla([
+          { type: "ITText", text: { $state: "folio" } },
+          {
+            type: "ITButton",
+            props: { label: "Crear", onClick: { action: "crear", then: [{ set: { folio: { $result: "id" } } }] } },
+          } as NodeSchema,
+        ])}
+        resolveAction={() => () => ({ id: "PED-7" })}
+      />
+    );
+    fireEvent.click(testingScreen.getByRole("button", { name: "Crear" }));
+    expect(testingScreen.getByText("PED-7")).toBeTruthy();
+  });
+
+  it("al cambiar de esquema, el estado vuelve al inicial del nuevo esquema", () => {
+    const primera = pantalla([{ type: "ITText", text: { $state: "titulo" } }], { titulo: "A" });
+    const { rerender } = render(<ITSchemaRenderer schema={primera} />);
+    expect(testingScreen.getByText("A")).toBeTruthy();
+
+    rerender(<ITSchemaRenderer schema={pantalla([{ type: "ITText", text: { $state: "titulo" } }], { titulo: "B" })} />);
+    expect(testingScreen.getByText("B")).toBeTruthy();
+  });
+});
+
+describe("JR061: permisos por acción", () => {
+  it("una acción que exige una capacidad no concedida no se ejecuta y avisa con JR061", () => {
+    const handler = vi.fn();
+    const { lista, onIssue } = avisos();
+    render(
+      <ITSchemaRenderer
+        schema={pantalla({
+          type: "ITButton",
+          props: { label: "Borrar", onClick: { action: "borrar", requires: "usuarios.eliminar" } },
+        })}
+        resolveAction={() => handler}
+        onIssue={onIssue}
+      />
+    );
+    fireEvent.click(testingScreen.getByRole("button", { name: "Borrar" }));
+    expect(handler).not.toHaveBeenCalled();
+    expect(lista.some((aviso) => aviso.code === "JR061")).toBe(true);
+  });
+
+  it("con la capacidad concedida, la acción sí se ejecuta", () => {
+    const handler = vi.fn();
+    render(
+      <ITSchemaRenderer
+        schema={pantalla({
+          type: "ITButton",
+          props: { label: "Borrar", onClick: { action: "borrar", requires: "usuarios.eliminar" } },
+        })}
+        resolveAction={() => handler}
+        capabilities={["usuarios.eliminar"]}
+      />
+    );
+    fireEvent.click(testingScreen.getByRole("button", { name: "Borrar" }));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("botones de fila en tablas", () => {
+  const tabla = (rowActions: unknown[]) =>
+    pantalla({
+      type: "ITDataTable",
+      props: {
+        columns: [
+          { key: "nombre", label: "Nombre", type: "string" },
+          { key: "acciones", label: "Acciones", type: "actions", rowActions },
+        ],
+        fetchData: { $source: "personas" },
+      },
+    }, undefined) as ScreenSchema;
+
+  const conFuente = (esquema: ScreenSchema) => ({
+    ...esquema,
+    data: { personas: { handler: "personas" } },
+  }) as ScreenSchema;
+
+  const filas = { personas: async () => ({ data: [{ id: 1, nombre: "Ana" }], total: 1 }) };
+
+  it("cada fila muestra el botón declarado y pulsarlo llama a la acción con la fila", async () => {
+    const ver = vi.fn();
+    render(
+      <ITSchemaRenderer
+        schema={conFuente(tabla([{ label: "Ver", action: "ver" }]))}
+        dataHandlers={filas}
+        resolveAction={(_node, _prop, accion) => ((accion as { action?: string }).action === "ver" ? ver : undefined)}
+      />
+    );
+    const boton = await testingScreen.findByRole("button", { name: "Ver" });
+    fireEvent.click(boton);
+    expect(ver).toHaveBeenCalledWith(expect.objectContaining({ id: 1, nombre: "Ana" }));
+  });
+
+  it("un botón de fila sin handler no se pinta y avisa con JR040", async () => {
+    const { lista, onIssue } = avisos();
+    render(
+      <ITSchemaRenderer
+        schema={conFuente(tabla([{ label: "Borrar", action: "no-existe" }]))}
+        dataHandlers={filas}
+        resolveAction={() => undefined}
+        onIssue={onIssue}
+      />
+    );
+    await waitFor(() => expect(lista.some((aviso) => aviso.code === "JR040")).toBe(true));
+    expect(testingScreen.queryByRole("button", { name: "Borrar" })).toBeNull();
+  });
+
+  it("un botón de fila sin action avisa con JR021", async () => {
+    const { lista, onIssue } = avisos();
+    render(
+      <ITSchemaRenderer
+        schema={conFuente(tabla([{ label: "Roto" }]))}
+        dataHandlers={filas}
+        resolveAction={() => () => undefined}
+        onIssue={onIssue}
+      />
+    );
+    await waitFor(() => expect(lista.some((aviso) => aviso.code === "JR021")).toBe(true));
+  });
+});

package/src/json-renderer/form/FormNode.tsx

@@ -0,0 +1,92 @@
+/**
+ * Nodo `form` del motor: campos declarados en JSON, validación y envío por acción.
+ *
+ * El esquema describe los campos; el motor los pinta con `ITInput`, valida al enviar
+ * y muestra el error bajo cada campo. Los valores válidos salen por la acción
+ * `onSubmit` que resuelve el host: el host decide qué hacer con ellos.
+ */
+
+import React, { useState } from "react";
+import ITButton from "../../components/atoms/button/button";
+import ITFlex from "../../components/atoms/flex/flex";
+import ITInput from "../../components/atoms/input/input";
+import ITStack from "../../components/atoms/stack/stack";
+import { useITTranslation } from "../../i18n/useITTranslation";
+import { validateForm, type FormField, type FormRuleCode } from "./rules";
+
+/** Props del nodo `form` ya resueltos por el renderizador. */
+export interface FormNodeProps {
+  /** Id del nodo: se refleja en el DOM como ancla. */
+  id?: string;
+  /** Campos, con sus textos ya traducidos. */
+  fields: FormField[];
+  /** Texto del botón de envío. Sin valor, `jsonRenderer.form.submit`. */
+  submitLabel?: string;
+  /** Acción del host: recibe los valores de los campos cuando el formulario es válido. */
+  onSubmit?: (values: Record<string, string>) => void;
+}
+
+/** Valor de un evento o de un valor directo de `ITInput`. */
+function valorDe(evento: unknown): string {
+  if (typeof evento === "string") return evento;
+  return (evento as { target?: { value?: unknown } } | null)?.target?.value?.toString() ?? "";
+}
+
+/**
+ * Formulario declarado en JSON. Nunca lanza por los valores que escribe el usuario.
+ *
+ * @example
+ * <FormNode fields={[{ name: "correo", kind: "email", label: "Correo", required: true }]}
+ *           submitLabel="Enviar" onSubmit={(valores) => console.log(valores)} />
+ */
+export function FormNode({ id, fields, submitLabel, onSubmit }: FormNodeProps) {
+  const { t } = useITTranslation();
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [errors, setErrors] = useState<Record<string, FormRuleCode>>({});
+  // Desde el primer envío, los campos se consideran tocados: sus errores se muestran.
+  const [intentado, setIntentado] = useState(false);
+
+  /** Mensaje traducido para un error de campo. Las longitudes van como parámetros. */
+  const mensaje = (code: FormRuleCode, campo: FormField) =>
+    t(`jsonRenderer.form.${code}`, { min: String(campo.minLength ?? 0), max: String(campo.maxLength ?? 0) });
+
+  const enviar = () => {
+    const encontrados = validateForm(fields, values);
+    setIntentado(true);
+    setErrors(encontrados);
+    if (Object.keys(encontrados).length === 0) onSubmit?.(values);
+  };
+
+  return (
+    <div id={id}>
+      <ITStack direction="column" spacing={3} alignItems="stretch">
+        {fields.map((field) => (
+          <ITInput
+            key={field.name}
+            name={field.name}
+            label={field.label}
+            type={field.kind === "email" ? "email" : "text"}
+            value={values[field.name] ?? ""}
+            touched={intentado}
+            error={errors[field.name] ? mensaje(errors[field.name], field) : undefined}
+            onChange={(evento: unknown) => {
+              const valor = valorDe(evento);
+              setValues((previo) => ({ ...previo, [field.name]: valor }));
+              setErrors((previo) => {
+                if (!previo[field.name]) return previo;
+                const resto = { ...previo };
+                delete resto[field.name];
+                return resto;
+              });
+            }}
+          />
+        ))}
+        <ITFlex>
+          <ITButton label={submitLabel ?? t("jsonRenderer.form.submit")} size="sm" onClick={enviar} />
+        </ITFlex>
+      </ITStack>
+    </div>
+  );
+}
+
+export default FormNode;