@axzydev/axzy_ui_system 1.7.2 → 1.7.4

package/src/json-renderer/kernel/renderNode.tsx

@@ -9,10 +9,48 @@
 import React from "react";
 import type { Catalog } from "../catalog/catalog.props";
 import { resolveNode } from "../catalog/resolve";
-import type { JsonEngineIssue } from "../shared/errors";
-import type { SchemaPath } from "../shared/paths";
+import { issue, type JsonEngineIssue } from "../shared/errors";
+import { formatPath, propPath, type SchemaPath } from "../shared/paths";
 import { isNodePending } from "../stream/tolerantParse";
+import { isSlotNode, slotName, type SlotRegistry } from "./slots";
 import type { NodeSchema } from "./types";
+import { FormNode } from "../form/FormNode";
+import { readFormFields, type FormField } from "../form/rules";
+import { wrapAction, type EffectContext, type EffectRegistry } from "../actions/effects";
+import { faltanCapacidades } from "./capabilities";
+import ITButton from "../../components/atoms/button/button";
+
+/** Contexto de efectos de un nodo: el registro del host, la traducción y los avisos. */
+function effectContext(options: RenderNodeOptions, path: SchemaPath, node: NodeSchema): EffectContext {
+  return {
+    effects: options.effects,
+    path,
+    resolveText: (value, valuePath) => textoDe(options.resolveValue ? options.resolveValue(value, valuePath) : value),
+    report: (aviso) => options.issues.push(aviso),
+    // Una acción encadenada desde un efecto se resuelve con el mismo `resolveAction` del host.
+    resolveChained: (name) => options.resolveAction?.(node, "chain", { action: name }, path),
+    timeoutMs: options.actionTimeoutMs,
+    reportRuntime: options.onIssue,
+    setState: options.setState,
+    resolveRaw: (value, valuePath) => (options.resolveValue ? options.resolveValue(value, valuePath) : value),
+  };
+}
+
+/** Nombre de una acción declarada, para los avisos. */
+function nombreDeAccion(action: unknown): string {
+  const nombre = (action as { action?: unknown } | null)?.action;
+  return typeof nombre === "string" ? nombre : "(sin nombre)";
+}
+
+/** `true` cuando el nodo es un formulario del motor. */
+function isFormNode(node: NodeSchema): boolean {
+  return node.type === "form";
+}
+
+/** Texto de un valor ya resuelto: solo los primitivos se muestran. */
+function textoDe(value: unknown): string {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : "";
+}
 
 /** Opciones de render de un nodo. */
 export interface RenderNodeOptions {
@@ -31,6 +69,18 @@ export interface RenderNodeOptions {
     action: unknown,
     path: SchemaPath
   ) => ((...args: unknown[]) => void) | undefined;
+  /** Slots que registra el host. Un nodo `slot` monta el componente con su nombre. */
+  slots?: SlotRegistry;
+  /** Efectos que cumple el host (`toast`, `navigate`…) tras una acción. */
+  effects?: EffectRegistry;
+  /** Milisegundos que una acción puede tardar antes de considerarla colgada (`JR041`). */
+  actionTimeoutMs?: number;
+  /** Escribe en el estado de la pantalla (efecto `set`). */
+  setState?: (cambios: Record<string, unknown>) => void;
+  /** Capacidades que concede el host (para las acciones con `requires`). */
+  capabilities?: readonly string[];
+  /** Recibe los avisos que se producen fuera del render (por ejemplo, un timeout). */
+  onIssue?: (aviso: JsonEngineIssue) => void;
   /** Renderiza los hijos de un nodo (lo aporta el recorrido del árbol). */
   renderChildren?: (node: NodeSchema, path: SchemaPath) => React.ReactNode;
   /** Qué pintar mientras un nodo está pendiente (streaming). */
@@ -55,6 +105,174 @@ export function childList(node: NodeSchema | null | undefined): NodeSchema[] {
   return Array.isArray(node.children) ? node.children : [node.children];
 }
 
+/**
+ * Monta un slot: el componente que el host registró con el nombre del nodo.
+ *
+ * Se monta como componente (no se llama como función) para que pueda usar hooks.
+ * Los props del nodo pasan por `resolveValue`, igual que los del resto de nodos.
+ */
+function renderSlot(node: NodeSchema, options: RenderNodeOptions): React.ReactNode {
+  const { path, issues, slots, resolveValue } = options;
+  const name = slotName(node);
+
+  if (!name) {
+    issues.push(
+      issue("JR011", "El slot no declara `props.name`.", formatPath(propPath(path, "name")), {
+        severity: "error",
+        hint: 'Declara el nombre que el host registró, por ejemplo { "type": "slot", "props": { "name": "resumen" } }.',
+      })
+    );
+    return null;
+  }
+
+  const Component = slots && Object.prototype.hasOwnProperty.call(slots, name) ? slots[name] : undefined;
+  if (!Component) {
+    issues.push(
+      issue("JR010", `El slot \`${name}\` no está registrado por el host.`, formatPath(path), {
+        severity: "error",
+        hint: "El host debe registrarlo en `slots` del renderizador.",
+      })
+    );
+    return null;
+  }
+
+  const props: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(node.props ?? {})) {
+    if (key === "name") continue;
+    props[key] = resolveValue ? resolveValue(raw, path) : raw;
+  }
+
+  return React.createElement(Component, { key: node.id ?? path.join("-"), ...props });
+}
+
+/**
+ * Pinta un nodo `form`: campos declarados en JSON, validación y envío por la acción del host.
+ *
+ * Los campos se leen con las mismas reglas que el validador (`readFormFields`). Los
+ * textos (etiquetas, botón) pasan por `resolveValue`, así que pueden ser `{ i18n }`.
+ */
+function renderForm(node: NodeSchema, options: RenderNodeOptions): React.ReactNode {
+  const { path, issues, resolveValue, resolveAction } = options;
+  const { fields: declarados, issues: avisos } = readFormFields(node.props?.fields, [...path, "props", "fields"]);
+  issues.push(...avisos);
+
+  const campos: FormField[] = declarados.map((campo, index) => {
+    const etiqueta = resolveValue ? resolveValue(campo.label, [...path, "props", "fields", index]) : campo.label;
+    return {
+      name: campo.name,
+      kind: campo.kind,
+      required: campo.required,
+      minLength: campo.minLength,
+      maxLength: campo.maxLength,
+      label: textoDe(etiqueta) || campo.name,
+    };
+  });
+
+  const textoEnvio = node.props?.submitLabel;
+  // Sin texto declarado, el nodo usa `jsonRenderer.form.submit` (lo resuelve FormNode).
+  const submitLabel = textoDe(resolveValue ? resolveValue(textoEnvio, path) : textoEnvio) || undefined;
+  const accion = resolveAction?.(node, "onSubmit", node.props?.onSubmit, path);
+  if (node.props?.onSubmit !== undefined && typeof accion !== "function") {
+    issues.push(
+      issue("JR040", `La acción "${nombreDeAccion(node.props.onSubmit)}" no está registrada por el host.`, formatPath(propPath(path, "onSubmit")), {
+        severity: "warning",
+        hint: "Regístrala en `resolveAction` del host. Sin ella, enviar el formulario no hace nada.",
+      })
+    );
+  }
+  const conEfectos = accion ? wrapAction(accion, node.props?.onSubmit, effectContext(options, path, node)) : undefined;
+
+  return React.createElement(FormNode, {
+    key: node.id ?? path.join("-"),
+    id: node.id,
+    fields: campos,
+    submitLabel,
+    onSubmit: conEfectos ? (valores: Record<string, string>) => conEfectos(valores) : undefined,
+  });
+}
+
+/**
+ * Convierte las columnas `type: "actions"` con `rowActions` en columnas reales de la
+ * tabla. Cada botón de fila llama a la acción del host con la fila como primer argumento,
+ * igual que `onRowClick`. El JSON nunca da una función: solo nombra la acción.
+ *
+ * Un botón sin handler, sin permiso o mal formado no se pinta y avisa (JR040, JR061, JR021).
+ */
+function prepararColumnas(columnas: unknown, node: NodeSchema, options: RenderNodeOptions, path: SchemaPath): unknown {
+  if (!Array.isArray(columnas)) return columnas;
+
+  return columnas.map((columna, indice) => {
+    if (!columna || typeof columna !== "object") return columna;
+    const declarada = columna as Record<string, unknown>;
+    if (declarada.type !== "actions" || !Array.isArray(declarada.rowActions)) return columna;
+
+    const colPath = [...path, "props", "columns", indice];
+    const botones = declarada.rowActions.flatMap((raw, indiceAccion) => {
+      const accion = raw as Record<string, unknown> | null;
+      const rutaAccion = [...colPath, "rowActions", indiceAccion];
+      if (!accion || typeof accion.action !== "string" || accion.action === "") {
+        options.issues.push(issue("JR021", "Un botón de fila no declara `action`.", formatPath(rutaAccion), { severity: "error" }));
+        return [];
+      }
+      const faltan = faltanCapacidades(accion.requires, options.capabilities);
+      if (faltan.length > 0) {
+        options.issues.push(
+          issue("JR061", `El botón de fila "${accion.action}" exige ${faltan.join(", ")}, que no está concedido.`, formatPath(rutaAccion), {
+            severity: "warning",
+            hint: "Concede la capacidad con la prop `capabilities` del renderizador.",
+          })
+        );
+        return [];
+      }
+      const handler = options.resolveAction?.(node, `fila:${accion.action}`, accion, rutaAccion);
+      if (typeof handler !== "function") {
+        options.issues.push(
+          issue("JR040", `La acción de fila "${accion.action}" no está registrada por el host.`, formatPath(rutaAccion), {
+            severity: "warning",
+            hint: "Regístrala en `resolveAction` del host, o quita el botón del esquema.",
+          })
+        );
+        return [];
+      }
+      const etiqueta = textoDe(options.resolveValue ? options.resolveValue(accion.label, rutaAccion) : accion.label);
+      return [
+        {
+          clave: String(indiceAccion),
+          etiqueta: etiqueta || accion.action,
+          color: typeof accion.color === "string" ? accion.color : "secondary",
+          variante: typeof accion.variant === "string" ? accion.variant : "outlined",
+          ejecutar: wrapAction(handler, accion, effectContext(options, rutaAccion, node)),
+        },
+      ];
+    });
+
+    const copia: Record<string, unknown> = { ...declarada };
+    delete copia.rowActions;
+    const etiquetaColumna = textoDe(options.resolveValue ? options.resolveValue(copia.label, colPath) : copia.label);
+    const Boton = ITButton as unknown as React.ComponentType<Record<string, unknown>>;
+
+    return {
+      ...copia,
+      label: etiquetaColumna || String(copia.key ?? ""),
+      actions: (fila: unknown) =>
+        React.createElement(
+          React.Fragment,
+          null,
+          botones.map((boton) =>
+            React.createElement(Boton, {
+              key: boton.clave,
+              label: boton.etiqueta,
+              size: "sm",
+              variant: boton.variante,
+              color: boton.color,
+              onClick: () => boton.ejecutar(fila),
+            })
+          )
+        ),
+    };
+  });
+}
+
 /**
  * Pinta un nodo del esquema.
  *
@@ -73,6 +291,16 @@ export function renderNode(node: NodeSchema, options: RenderNodeOptions): React.
     return options.pendingFallback ?? null;
   }
 
+  // Los slots no están en el catálogo: los registra el host.
+  if (isSlotNode(node)) {
+    return renderSlot(node, options);
+  }
+
+  // El formulario lo compila el motor: campos, validación y envío por acción.
+  if (isFormNode(node)) {
+    return renderForm(node, options);
+  }
+
   const resolved = resolveNode(node, catalog, path);
   issues.push(...resolved.issues);
 
@@ -87,11 +315,36 @@ export function renderNode(node: NodeSchema, options: RenderNodeOptions): React.
   for (const [name, value] of Object.entries(props)) {
     finalProps[name] = options.resolveValue ? options.resolveValue(value, path) : value;
   }
+  // Las tablas reciben las columnas con sus botones de fila ya convertidos en funciones.
+  if (node.type === "ITDataTable" && finalProps.columns !== undefined) {
+    finalProps.columns = prepararColumnas(finalProps.columns, node, options, path);
+  }
 
   // Las acciones se traducen a handlers del host; las no registradas se avisan.
   for (const [name, action] of Object.entries(actions)) {
+    // Permisos por acción: una acción que exige algo no concedido no se ejecuta (JR061).
+    const faltan = faltanCapacidades((action as { requires?: unknown } | null)?.requires, options.capabilities);
+    if (faltan.length > 0) {
+      issues.push(
+        issue("JR061", `La acción "${nombreDeAccion(action)}" exige ${faltan.join(", ")}, que no está concedido.`, formatPath(propPath(path, name)), {
+          severity: "warning",
+          hint: "Concede la capacidad con la prop `capabilities` del renderizador. Sin ella, la acción no se ejecuta.",
+        })
+      );
+      continue;
+    }
     const handler = options.resolveAction?.(node, name, action, path);
-    if (typeof handler === "function") finalProps[name] = handler;
+    if (typeof handler === "function") {
+      finalProps[name] = wrapAction(handler, action, effectContext(options, path, node));
+    } else {
+      // Sin handler, el botón no hace nada: que se note en vez de fallar en silencio.
+      issues.push(
+        issue("JR040", `La acción "${nombreDeAccion(action)}" no está registrada por el host.`, formatPath(propPath(path, name)), {
+          severity: "warning",
+          hint: "Regístrala en `resolveAction` del host, o quita la prop del esquema.",
+        })
+      );
+    }
   }
 
   // Contenido: `children` declarados y, si el componente acepta texto, el atajo.

package/src/json-renderer/kernel/schemaRenderer.props.ts

@@ -3,7 +3,10 @@ import type { Catalog } from "../catalog/catalog.props";
 import type { JsonEngineIssue } from "../shared/errors";
 import type { EngineLimits } from "../shared/limits";
 import type { SchemaPath } from "../shared/paths";
-import type { NodeSchema, ScreenSchema } from "./types";
+import type { DataHandler } from "../binding/resolveValue";
+import type { SlotRegistry } from "./slots";
+import type { EffectRegistry } from "../actions/effects";
+import type { NodeSchema, ScreenSchema, SchemaValue } from "./types";
 
 /**
  * Props de `ITSchemaRenderer`.
@@ -18,9 +21,32 @@ export interface ITJsonRenderEngineProps {
   catalog?: Catalog;
   /** Presupuesto de nodos, profundidad y tiempos. */
   limits?: Partial<EngineLimits>;
+  /** Valores de la ruta para `$param`. Los pone el host; el esquema no puede crearlos. */
+  params?: Record<string, SchemaValue>;
   /**
-   * Resuelve un valor declarativo del esquema (`$state`, `$param`, `$source`…) al
-   * valor real. Sin esta prop, los valores se pasan tal cual (útil para pruebas).
+   * Handlers de datos que registra el host, por nombre. Las fuentes de `data` los
+   * referencian con `handler`. Conviene memoizarlo: cada fuente se resuelve contra él.
+   */
+  dataHandlers?: Record<string, DataHandler>;
+  /**
+   * Bloques JSX que registra el host, por nombre. Un nodo `{ "type": "slot", "props": { "name": "…" } }`
+   * monta el componente con ese nombre; el esquema no puede elegir otro.
+   */
+  slots?: SlotRegistry;
+  /**
+   * Efectos que cumple el host. Una acción con `then`, `onError` o efectos sueltos
+   * los ejecuta después de su handler; `toast` y `navigate` son los más comunes.
+   */
+  effects?: EffectRegistry;
+  /**
+   * Capacidades que concede el host (`["usuarios.leer", …]`). Un nodo o la pantalla que
+   * declara `requires` solo se pinta si todas están concedidas; si no, avisa con `JR060`.
+   * Sin esta prop, cualquier `requires` se deniega.
+   */
+  capabilities?: readonly string[];
+  /**
+   * Resuelve los valores que no son referencias del motor (por ejemplo, textos
+   * `{ i18n }`). Las referencias `$source`, `$state` y `$param` las resuelve el motor.
    */
   resolveValue?: (value: unknown, path: SchemaPath) => unknown;
   /**

package/src/json-renderer/kernel/slots.test.tsx

@@ -0,0 +1,104 @@
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen as testingScreen } from "@testing-library/react";
+import { validateSchema } from "../validation/validate";
+import type { JsonEngineIssue } from "../shared/errors";
+import { ITSchemaRenderer } from "./SchemaRenderer";
+import type { SlotRegistry } from "./slots";
+import type { NodeSchema, ScreenSchema } from "./types";
+
+/** Esquema mínimo con el contenido indicado. */
+const screen = (content: NodeSchema | NodeSchema[], extra: Partial<ScreenSchema> = {}): ScreenSchema => ({
+  version: 1,
+  id: "slots",
+  content,
+  ...extra,
+});
+
+/** Acumula los avisos del renderizador. */
+function collectIssues() {
+  const issues: JsonEngineIssue[] = [];
+  return { issues, onIssue: (issue: JsonEngineIssue) => issues.push(issue) };
+}
+
+describe("slots", () => {
+  it("monta el componente registrado con los props del nodo ya resueltos, sin el nombre", () => {
+    const Resumen = vi.fn((props: Record<string, unknown>) => <p>{`Resumen ${String(props.titulo)}`}</p>);
+    const slots: SlotRegistry = { resumen: Resumen };
+
+    render(
+      <ITSchemaRenderer
+        schema={screen(
+          { type: "slot", props: { name: "resumen", titulo: { $state: "titulo" } } },
+          { state: { titulo: "Pedidos" } }
+        )}
+        slots={slots}
+      />
+    );
+
+    expect(testingScreen.getByText("Resumen Pedidos")).toBeTruthy();
+    const props = Resumen.mock.calls[0][0];
+    expect(props).toMatchObject({ titulo: "Pedidos" });
+    expect(props).not.toHaveProperty("name");
+  });
+
+  it("un nombre que el host no registró avisa con JR010 y no pinta nada", () => {
+    const { issues, onIssue } = collectIssues();
+    const { container } = render(
+      <ITSchemaRenderer
+        schema={screen([
+          { type: "slot", props: { name: "inexistente" } },
+          { type: "ITText", text: "resto" },
+        ])}
+        slots={{}}
+        onIssue={onIssue}
+      />
+    );
+
+    expect(issues.some((issue) => issue.code === "JR010" && issue.message.includes("inexistente"))).toBe(true);
+    expect(testingScreen.getByText("resto")).toBeTruthy();
+    expect(container.textContent).toBe("resto");
+  });
+
+  it("un slot sin `props.name` avisa con JR011", () => {
+    const { issues, onIssue } = collectIssues();
+    render(<ITSchemaRenderer schema={screen({ type: "slot", props: {} })} slots={{}} onIssue={onIssue} />);
+    expect(issues.some((issue) => issue.code === "JR011")).toBe(true);
+  });
+
+  it("un slot que lanza se aísla: el resto de la pantalla sigue pintándose", () => {
+    const { issues, onIssue } = collectIssues();
+    const Roto = () => {
+      throw new Error("fallo del slot");
+    };
+    const errorConsola = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    render(
+      <ITSchemaRenderer
+        schema={screen([
+          { type: "slot", props: { name: "roto" } },
+          { type: "ITText", text: "sigue viva" },
+        ])}
+        slots={{ roto: Roto }}
+        onIssue={onIssue}
+      />
+    );
+
+    expect(testingScreen.getByText("sigue viva")).toBeTruthy();
+    expect(issues.some((issue) => issue.code === "JR012")).toBe(true);
+    errorConsola.mockRestore();
+  });
+});
+
+describe("validación de slots", () => {
+  it("un slot con nombre es válido aunque el host lo registre después", () => {
+    const informe = validateSchema(screen({ type: "slot", props: { name: "resumen" } }));
+    expect(informe.verdict).toBe("valid");
+  });
+
+  it("un slot sin nombre es un error de validación (JR011)", () => {
+    const informe = validateSchema(screen({ type: "slot", props: { titulo: "x" } }));
+    expect(informe.verdict).toBe("invalid");
+    expect(informe.errors[0]).toMatchObject({ code: "JR011" });
+  });
+});

package/src/json-renderer/kernel/slots.ts

@@ -0,0 +1,34 @@
+/**
+ * Slots: bloques que registra el **host** y el esquema solo nombra.
+ *
+ * Un nodo `{ "type": "slot", "props": { "name": "…", … } }` monta el componente que
+ * el host registró con ese nombre en `slots`. El esquema no puede elegir el
+ * componente ni inyectar código: solo pasa valores (ya resueltos por el binding)
+ * como props. Es la vía para reutilizar pantallas JSX existentes dentro de un JSON.
+ *
+ * Los slots no están en el catálogo: son autoridad del host, igual que los handlers
+ * de datos. Un nombre que el host no registró avisa con `JR010` y no se pinta nada.
+ */
+
+import type { ComponentType } from "react";
+import type { NodeSchema } from "./types";
+
+/** Tipo de nodo reservado para los slots. Minúscula: lo compila el motor, no es un componente. */
+export const SLOT_TYPE = "slot";
+
+/** Componente que el host registra como slot. Recibe los props del nodo ya resueltos. */
+export type SlotComponent = ComponentType<Record<string, unknown>>;
+
+/** Slots que registra el host, por nombre. */
+export type SlotRegistry = Record<string, SlotComponent>;
+
+/** `true` cuando el nodo es un slot. */
+export function isSlotNode(node: NodeSchema): boolean {
+  return node.type === SLOT_TYPE;
+}
+
+/** Nombre del slot (`props.name`), o `undefined` si falta o no es texto. */
+export function slotName(node: NodeSchema): string | undefined {
+  const name = node.props?.name;
+  return typeof name === "string" && name !== "" ? name : undefined;
+}

package/src/json-renderer/kernel/types.ts

@@ -76,6 +76,10 @@ export interface EffectSchema {
   openOverlay?: string;
   /** Cierra el overlay indicado, o el que esté abierto si se omite. */
   closeOverlay?: string;
+  /** Escribe en el estado de la pantalla: `{ "clave": valor }`. Los valores admiten referencias. */
+  set?: Record<string, SchemaValue>;
+  /** Capacidad que exige la acción. Sin concesión, la acción no se ejecuta (`JR061`). */
+  requires?: string | string[];
   /** Refresca una fuente de datos. */
   refresh?: string;
 }

package/src/json-renderer/routing/match.ts

@@ -0,0 +1,82 @@
+/**
+ * Casa una dirección (path + query) con una ruta declarada.
+ *
+ * Reglas, de más a menos específica:
+ * 1. Más segmentos estáticos gana a un `:param` en la misma posición
+ *    (`/usuarios/nuevo` antes que `/usuarios/:id`).
+ * 2. Con el mismo path, gana la ruta que exige más claves de query
+ *    (`?estado=Activo` antes que la ruta sin query).
+ * 3. Empate: la primera declarada.
+ *
+ * Nunca lanza: una dirección que no casa devuelve `null`.
+ */
+
+import type { FlatRoute } from "./routes";
+
+/** Resultado de casar una dirección. */
+export interface RouteMatch {
+  /** Ruta que casa. */
+  route: FlatRoute;
+  /** Valores de los `:param` de la ruta, por nombre (sin los dos puntos). */
+  params: Record<string, string>;
+}
+
+/**
+ * Busca la ruta que corresponde a una dirección.
+ *
+ * @example
+ * matchRoute(flattenRoutes(routes), ["usuarios"], { estado: "Activo" })?.route.id; // "u-activos"
+ */
+export function matchRoute(
+  routes: FlatRoute[],
+  segments: string[],
+  query: Record<string, string> = {}
+): RouteMatch | null {
+  let best: RouteMatch | null = null;
+  let bestStatics = -1;
+  let bestConstraints = -1;
+
+  for (const route of routes) {
+    if (route.segments.length !== segments.length) continue;
+
+    const params: Record<string, string> = {};
+    let statics = 0;
+    let samePath = true;
+    route.segments.forEach((expected, index) => {
+      if (!samePath) return;
+      if (expected.startsWith(":")) {
+        params[expected.slice(1)] = segments[index];
+        return;
+      }
+      statics += 1;
+      samePath = expected === segments[index];
+    });
+    if (!samePath) continue;
+
+    const constraints = Object.entries(route.query);
+    if (!constraints.every(([key, value]) => query[key] === value)) continue;
+
+    // Un empate en estáticos y query conserva la ruta declarada antes (no se reemplaza).
+    if (statics > bestStatics || (statics === bestStatics && constraints.length > bestConstraints)) {
+      best = { route, params };
+      bestStatics = statics;
+      bestConstraints = constraints.length;
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Dirección (`/usuarios/42?estado=Activo`) de una ruta, con sus `:param` rellenos.
+ * Los `:param` sin valor se dejan tal cual para que se vean en el menú.
+ */
+export function routeHref(route: FlatRoute, params: Record<string, string> = {}): string {
+  const path = route.segments
+    .map((segment) => (segment.startsWith(":") ? (params[segment.slice(1)] ?? segment) : segment))
+    .join("/");
+  const queryString = Object.entries(route.query)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join("&");
+  return `/${path}${queryString ? `?${queryString}` : ""}`;
+}

package/src/json-renderer/routing/navigation.ts

@@ -0,0 +1,71 @@
+/**
+ * Árbol de navegación derivado de `routes.json`.
+ *
+ * Solo entran las rutas con `nav`. Un grupo con `nav` se convierte en una entrada con
+ * hijos y, como enlace, apunta a su primera hija con dirección. Un grupo sin `nav` no
+ * aparece: sus hijos suben de nivel. El host decide cómo pintar el árbol (sidebar, top
+ * bar…); el motor solo entrega la forma y las direcciones.
+ */
+
+import type { SchemaValue } from "../kernel/types";
+import { routeHref } from "./match";
+import { flattenRoutes, joinRoutePath, type RouteNavSchema, type RouteSchema } from "./routes";
+
+/** Entrada del árbol de navegación. */
+export interface NavNode {
+  /** Id de la ruta (o del grupo) de origen. */
+  id: string;
+  /** Texto de la entrada; puede ser una referencia `{ i18n }` que resuelve el host. */
+  label: SchemaValue;
+  /** Icono, tal como lo declara el JSON. */
+  icon?: string;
+  /** Contador de la entrada. */
+  badge?: number | string;
+  /** Dirección a la que lleva la entrada. Los grupos apuntan a su primera hija con dirección. */
+  href?: string;
+  /** Entradas hijas. Presentes solo en los grupos. */
+  children?: NavNode[];
+}
+
+/**
+ * Construye el árbol de navegación a partir de las rutas declaradas.
+ *
+ * @example
+ * buildNavigationTree(routes.routes)[0]; // { id: "inicio", label: {...}, href: "/inicio" }
+ */
+export function buildNavigationTree(routes: RouteSchema[]): NavNode[] {
+  // Las direcciones de las hojas se calculan una vez; un grupo usa las de sus hijas.
+  const hrefs = new Map(flattenRoutes(routes).map((route) => [route.id, routeHref(route)]));
+
+  const visit = (route: RouteSchema, parentPath: string): NavNode[] => {
+    const full = joinRoutePath(parentPath, route.path);
+
+    if (route.children) {
+      const children = route.children.flatMap((child) => visit(child, full));
+      if (!route.nav) return children;
+      return [toNode(route.id, route.nav, children, children.find((child) => child.href)?.href)];
+    }
+
+    if (!route.nav) return [];
+    return [toNode(route.id, route.nav, undefined, hrefs.get(route.id))];
+  };
+
+  return routes.flatMap((route) => visit(route, ""));
+}
+
+/** Crea una entrada a partir de su `nav` declarado. */
+function toNode(id: string, nav: RouteNavSchema, children: NavNode[] | undefined, href: string | undefined): NavNode {
+  return {
+    id,
+    label: nav.label,
+    icon: nav.icon,
+    badge: nav.badge,
+    href,
+    ...(children ? { children } : {}),
+  };
+}
+
+/** `true` cuando la entrada, o alguno de sus hijos, es la ruta indicada. */
+export function navContainsRoute(entry: NavNode, routeId: string): boolean {
+  return entry.id === routeId || (entry.children?.some((child) => navContainsRoute(child, routeId)) ?? false);
+}