@axzydev/axzy_ui_system 1.6.0 → 1.7.1

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();
+    }
+  });
+});