@axzydev/axzy_ui_system 1.6.0 → 1.7.1

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "type": "module",
   "sideEffects": [
     "*.css"
@@ -33,6 +33,8 @@
     "build:app": "tsc -b && vite build -c vite.app.config.ts",
     "build:css": "node scripts/build-css.mjs",
     "lint": "eslint . && node scripts/check-atomic-deps.mjs && node scripts/check-css-isolation.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "check:atomic": "node scripts/check-atomic-deps.mjs",
     "check:css": "node scripts/check-css-isolation.mjs",
     "preview": "vite preview",
@@ -44,7 +46,8 @@
     "ext:package": "node vscode-extension/esbuild.mjs && cd vscode-extension && npx --yes @vscode/vsce package --no-dependencies",
     "audit:sandbox": "node scripts/audit-sandbox.mjs",
     "docs:llm": "pnpm ext:catalog && node scripts/build-llm-docs.mjs && node scripts/build-ai-bundle.mjs",
-    "docs:ai": "node scripts/build-ai-bundle.mjs"
+    "docs:ai": "node scripts/build-ai-bundle.mjs",
+    "docs:json-renderer": "node scripts/build-json-renderer-docs.mjs"
   },
   "dependencies": {
     "clsx": "^2.1.1",
@@ -61,22 +64,26 @@
   },
   "devDependencies": {
     "@eslint/js": "9.19.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^22.13.1",
     "@types/react": "19.0.8",
     "@types/react-dom": "19.0.3",
+    "@types/vscode": "1.85.0",
     "@vitejs/plugin-react-swc": "3.8.0",
+    "esbuild": "^0.25.0",
     "eslint": "9.19.0",
     "eslint-plugin-react-hooks": "5.0.0",
     "eslint-plugin-react-refresh": "0.4.18",
     "globals": "15.14.0",
+    "jsdom": "^26.1.0",
+    "tailwindcss": "^4.0.0",
+    "tsup": "^8.3.6",
     "typescript": "~5.7.2",
     "typescript-eslint": "8.22.0",
     "vite": "6.1.0",
-    "@tailwindcss/vite": "^4.0.0",
-    "tailwindcss": "^4.0.0",
-    "tsup": "^8.3.6",
     "vite-plugin-dts": "^4.5.0",
-    "@types/vscode": "1.85.0",
-    "esbuild": "^0.25.0"
+    "vitest": "^3.2.7"
   }
 }

package/src/App.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useMemo, useState } from "react";
 import { ITLayout, ITThemeProvider, ITI18nProvider, useITTranslation, useDebouncedSearch } from "./index";
+import { DEFAULT_AXZY_CONFIG, mergeAxzyConfig, type AxzyConfig } from "./sandbox/axzyConfig";
 import type { ITNavigationItem } from "./index";
 
 // Import Showcases
@@ -65,6 +66,11 @@ import {
   LoaderShowcase,
   ThemeProviderShowcase,
 } from "./showcases/FeedbackShowcases";
+import JsonRendererShowcase from "./showcases/JsonRendererShowcase";
+import JsonEditorShowcase from "./showcases/JsonEditorShowcase";
+import JsonScreenShowcase from "./showcases/JsonScreenShowcase";
+import DemoJsonPortfolio from "./showcases/DemoJsonPortfolio";
+import DemoJsonDashboard, { DEMO_APP_PAGES, type DemoAppPage } from "./showcases/DemoJsonDashboard";
 
 // Sandbox routing / landing (dev-only, never published)
 import {
@@ -75,6 +81,7 @@ import { useHashRoute } from "./sandbox/useHashRoute";
 import TopbarSearch from "./sandbox/TopbarSearch";
 import { LandingShowcase } from "./sandbox/LandingShowcase";
 import NotFoundShowcase from "./sandbox/NotFoundShowcase";
+import { AxzyLogo } from "./sandbox/AxzyLogo";
 import { sandboxMessages, translateLabel } from "./sandbox/i18n";
 import { SandboxLocaleProvider, useSandboxLocale } from "./sandbox/locale";
 import { SelectorIdioma, SelectorTema } from "./sandbox/controls";
@@ -87,7 +94,15 @@ import { GROUP_ICONS } from "./sandbox/icons";
  */
 function AppShell() {
   const { t } = useITTranslation();
-  const { route, goToItem, goToLanding, goToPortfolio } = useHashRoute();
+  const { route, goToItem, goToLanding, goToPortfolio, goToDemo } = useHashRoute();
+  // Configuración global del sandbox: `public/axzy.json`.
+  const [configGlobal, setConfigGlobal] = useState<AxzyConfig>(DEFAULT_AXZY_CONFIG);
+  useEffect(() => {
+    fetch("/axzy.json")
+      .then((r) => r.json())
+      .then((json: unknown) => setConfigGlobal(mergeAxzyConfig(json)))
+      .catch(() => setConfigGlobal(DEFAULT_AXZY_CONFIG));
+  }, []);
   const [subitemConnector] = useState<"dot" | "|" | "none">("dot");
 
   // Debounced term drives filtering; `searchValue` is the live input value.
@@ -172,6 +187,9 @@ function AppShell() {
   };
 
   const topBarProps = {
+    // La marca axzydev sustituye al nombre suelto: el wordmark ya dice a quién
+    // pertenece el catálogo y el texto se mantiene como respaldo accesible.
+    logo: <AxzyLogo variante="icono" tamano={22} />,
     logoText: "AXZY UI System",
     centerContent: (
       <TopbarSearch
@@ -202,10 +220,16 @@ function AppShell() {
         label: t("sandbox.nav.portfolio"),
         action: () => goToPortfolio(),
       },
+      {
+        id: "demo",
+        label: t("sandbox.nav.demo"),
+        action: () => goToDemo(),
+      },
     ],
     onNavItemClick: (id: string) => {
       if (id === "ui-system") goToLanding();
       else if (id === "portfolio") goToPortfolio();
+      else if (id === "demo") goToDemo();
     },
     // Sin `userMenu`: el sandbox no tiene sesión. Antes mostraba un usuario
     // inventado ("Alex Dev / alex@axzy.dev") en un portafolio real.
@@ -309,6 +333,12 @@ function AppShell() {
         return <LoaderShowcase />;
       case "themeprovider":
         return <ThemeProviderShowcase />;
+      case "jsonrenderer":
+        return <JsonRendererShowcase />;
+      case "jsoneditor":
+        return <JsonEditorShowcase />;
+      case "jsonscreen":
+        return <JsonScreenShowcase />;
       default:
         return (
           <NotFoundShowcase
@@ -321,7 +351,14 @@ function AppShell() {
   };
 
   return (
-    <ITThemeProvider showFab={false} density={0.98} radius={10} shadow={2}>
+    <ITThemeProvider
+      showFab={configGlobal.showFab}
+      density={configGlobal.density}
+      radius={configGlobal.radius}
+      shadow={configGlobal.shadow}
+      appearance={configGlobal.appearance}
+      theme={configGlobal.theme}
+    >
         {route.view === "producto" ? (
           <div className="min-h-[100dvh] bg-[#fafafa] dark:bg-[#0b0d10]">
             {route.valid ? (
@@ -337,6 +374,37 @@ function AppShell() {
               />
             )}
           </div>
+        ) : route.view === "demo" ? (
+          route.group === "app" ? (
+            <DemoJsonDashboard
+              page={(DEMO_APP_PAGES.includes((route.item ?? "inicio") as DemoAppPage)
+                ? route.item
+                : "inicio") as DemoAppPage}
+              onNavigate={(pagina) => {
+                window.location.hash = `#demo/app/${pagina}`;
+              }}
+              onExit={() => {
+                window.location.hash = "#demo";
+              }}
+              filterEstado={route.query.estado ?? "Todos"}
+              onFilterChange={(estado) => {
+                const base = `#demo/app/${route.item ?? "inicio"}`;
+                window.location.hash = estado === "Todos" ? base : `${base}?estado=${encodeURIComponent(estado)}`;
+              }}
+            />
+          ) : (
+            <div className="min-h-[100dvh] bg-[#fafafa] dark:bg-[#0b0d10]">
+              <DemoJsonPortfolio
+                onBack={() => goToLanding()}
+                onOpenProject={(id) => {
+                  window.location.hash = `#proyecto/${id}`;
+                }}
+                onOpenPanel={() => {
+                  window.location.hash = "#demo/app/inicio";
+                }}
+              />
+            </div>
+          )
         ) : route.view === "home" ? (
           <div className="min-h-[100dvh] bg-[#fafafa] dark:bg-[#0b0d10]">
             <HomeShowcase />

package/src/components/atoms/image/image.props.ts

@@ -7,6 +7,8 @@ export interface ITImageProps {
   className?: string;
   /** Fallback image URL shown when the primary `src` fails to load */
   fallback?: string;
+  /** How the image fills its box: "cover" crops to fill (default), "contain" shows the whole image */
+  fit?: "cover" | "contain";
   /** Click handler */
   onClick?: () => void;
 }

package/src/components/atoms/image/image.tsx

@@ -26,6 +26,7 @@ const ITImage = ({
   alt,
   className = "",
   fallback = "",
+  fit = "cover",
 }: ITImageProps) => {
   const [imageError, setImageError] = useState(false);
   const { t } = useITTranslation();
@@ -42,14 +43,14 @@ const ITImage = ({
         <img
           src={fallback}
           alt={t("image.fallbackAlt")}
-          className="w-full h-full object-cover"
+          className="w-full h-full" style={{ objectFit: fit }}
         />
       ) : (
         <img
           src={src}
           alt={alt}
           onError={handleImageError}
-          className="w-full h-full object-cover"
+          className="w-full h-full" style={{ objectFit: fit }}
         />
       )}
     </div>

package/src/components/molecules/json-editor/json-editor-tree.tsx

@@ -0,0 +1,235 @@
+import React, { useMemo, useState } from "react";
+import clsx from "clsx";
+import { FaChevronDown, FaChevronRight, FaCrosshairs } from "react-icons/fa";
+import { useITTranslation } from "@/i18n";
+import { pathKey, previewValue, valueKind, type ITCodeAnalysis } from "./json-editor.utils";
+
+/** Un nodo del árbol ya resuelto, listo para pintar. */
+interface TreeNode {
+  /** Clave o índice con el que se muestra (vacío en la raíz). */
+  label: string;
+  /** Ruta absoluta dentro del documento, como clave estable. */
+  key: string;
+  /** Ruta absoluta troceada (evita re-parsear la clave: las claves pueden llevar puntos). */
+  path: (string | number)[];
+  /** Profundidad de anidación (la raíz es 0). */
+  level: number;
+  /** Valor del nodo. */
+  value: unknown;
+  /** Tipo del valor. */
+  kind: ReturnType<typeof valueKind>;
+  /** Número de hijos directos. */
+  childCount: number;
+  /** Hijos, solo en objetos y arrays. */
+  children: TreeNode[];
+}
+
+/** Props de `ITCodeTreeView`. */
+export interface ITCodeTreeViewProps {
+  /** Valor ya parseado que hay que representar. */
+  value: unknown;
+  /** Análisis del texto, para poder saltar a la línea de cada nodo. */
+  analysis: ITCodeAnalysis;
+  /** Muestra la línea de cada nodo y permite saltar a ella. @default false */
+  showLines?: boolean;
+  /** Se dispara al pulsar el botón de salto de un nodo. */
+  onJumpToLine?: (line: number) => void;
+  /** Clases del contenedor. */
+  className?: string;
+}
+
+/** Número máximo de filas pintadas; evita colgar la vista con JSON enormes. */
+const MAX_ROWS = 1500;
+/** Niveles que vienen desplegados al abrir el árbol. */
+const AUTO_EXPANDED_LEVELS = 2;
+
+/** Construye el árbol de nodos a partir de un valor ya parseado. */
+function buildTree(
+  value: unknown,
+  label: string,
+  path: (string | number)[],
+  level: number
+): TreeNode {
+  const kind = valueKind(value);
+  const children: TreeNode[] = [];
+  if (kind === "object") {
+    for (const [childKey, nested] of Object.entries(value as Record<string, unknown>)) {
+      children.push(buildTree(nested, childKey, [...path, childKey], level + 1));
+    }
+  } else if (kind === "array") {
+    (value as unknown[]).forEach((nested, index) => {
+      children.push(buildTree(nested, String(index), [...path, index], level + 1));
+    });
+  }
+  return {
+    label,
+    key: pathKey(path),
+    path,
+    level,
+    value,
+    kind,
+    childCount: children.length,
+    children,
+  };
+}
+
+/**
+ * `ITCodeTreeView` — árbol navegable de un JSON ya parseado.
+ *
+ * Pieza visual interna de `ITJSONEditor`: no valida ni parsea, solo pinta lo que
+ * recibe. Se exporta aparte por si hace falta reutilizarla en paneles o en
+ * documentación.
+ *
+ * @example
+ * ```tsx
+ * <ITCodeTreeView value={{ a: 1 }} analysis={analysis} showLines onJumpToLine={setLine} />
+ * ```
+ */
+export default function ITCodeTreeView({
+  value,
+  analysis,
+  showLines = false,
+  onJumpToLine,
+  className,
+}: ITCodeTreeViewProps) {
+  const { t } = useITTranslation();
+  const root = useMemo(() => buildTree(value, "", [], 0), [value]);
+  /** Nodos plegados por el usuario; el resto sigue la heurística de niveles. */
+  const [collapsed, setCollapsed] = useState<Record<string, boolean>>({});
+
+  /** Filas visibles ya aplanadas, con el corte por `MAX_ROWS` aplicado. */
+  const rows = useMemo(() => {
+    const result: TreeNode[] = [];
+    const isOpen = (node: TreeNode) => {
+      const explicit = collapsed[node.key];
+      if (explicit !== undefined) return !explicit;
+      return node.level < AUTO_EXPANDED_LEVELS;
+    };
+    const walk = (node: TreeNode) => {
+      if (result.length >= MAX_ROWS) return;
+      result.push(node);
+      if (node.childCount && isOpen(node)) node.children.forEach(walk);
+    };
+    if (root.kind === "object" || root.kind === "array") root.children.forEach(walk);
+    else result.push(root);
+    return result;
+  }, [root, collapsed]);
+
+  const truncated = rows.length >= MAX_ROWS;
+
+  const toggle = (key: string, level: number) =>
+    setCollapsed((previous) => ({
+      ...previous,
+      // Sin decisión previa, la fila estaba abierta si su nivel se auto-despliega.
+      [key]: previous[key] === undefined ? level < AUTO_EXPANDED_LEVELS : !previous[key],
+    }));
+
+  return (
+    <div tabIndex={0} className={clsx("it-json-editor-tree overflow-auto", className)}>
+      {rows.map((node) => {
+        const line = analysis.nodeLines.get(pathKey(node.path))?.line;
+        const isRoot = node.key === "";
+        const isCollapsed =
+          collapsed[node.key] ?? (node.childCount > 0 && node.level >= AUTO_EXPANDED_LEVELS);
+        const hasChildren = node.childCount > 0;
+        const isPrimitive = node.kind !== "object" && node.kind !== "array";
+
+        return (
+          <div
+            key={node.key || "root"}
+            className="it-json-editor-tree-row"
+            style={{ paddingLeft: node.level * 14 }}
+          >
+            {hasChildren ? (
+              <button
+                type="button"
+                onClick={() => toggle(node.key, node.level)}
+                aria-expanded={!isCollapsed}
+                aria-label={isCollapsed ? t("jsonEditor.expandNode") : t("jsonEditor.collapseNode")}
+                className="it-json-editor-tree-toggle"
+              >
+                {isCollapsed ? <FaChevronRight size={8} /> : <FaChevronDown size={8} />}
+              </button>
+            ) : (
+              <span className="it-json-editor-tree-spacer" aria-hidden="true" />
+            )}
+
+            {!isRoot && (
+              <>
+                <span className="it-json-editor-tk-key">{node.label}</span>
+                <span className="it-json-editor-tk-punct">:</span>
+              </>
+            )}
+
+            {hasChildren ? (
+              <>
+                <span className="it-json-editor-tk-punct">{node.kind === "array" ? "[" : "{"}</span>
+                {isCollapsed && (
+                  <span className="it-json-editor-tk-punct">
+                    {node.kind === "array" ? "]" : "}"}
+                  </span>
+                )}
+                <span className="it-json-editor-tree-badge">
+                  {t("jsonEditor.childCount", { count: node.childCount })}
+                </span>
+              </>
+            ) : (
+              <span
+                className={clsx(
+                  "it-json-editor-tk-value",
+                  node.kind === "string" && "it-json-editor-tk-string",
+                  node.kind === "number" && "it-json-editor-tk-number",
+                  node.kind === "boolean" && "it-json-editor-tk-keyword",
+                  node.kind === "null" && "it-json-editor-tk-null"
+                )}
+              >
+                {previewValue(node.value)}
+              </span>
+            )}
+
+            {isPrimitive && isRoot && (
+              <span className="it-json-editor-tree-badge">{kindLabel(node.kind, t)}</span>
+            )}
+
+            {showLines && line !== undefined && (
+              <button
+                type="button"
+                onClick={() => onJumpToLine?.(line)}
+                title={t("jsonEditor.jumpToLine", { line })}
+                aria-label={t("jsonEditor.jumpToLine", { line })}
+                className="it-json-editor-tree-jump"
+              >
+                <FaCrosshairs size={8} />
+                <span>{line}</span>
+              </button>
+            )}
+          </div>
+        );
+      })}
+
+      {truncated && (
+        <p className="it-json-editor-tree-badge m-2 inline-block px-2 py-1">
+          {t("jsonEditor.treeTruncated")}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/** Etiqueta corta y traducible del tipo de un valor. */
+function kindLabel(kind: TreeNode["kind"], t: (key: string) => string): string {
+  switch (kind) {
+    case "object":
+      return t("jsonEditor.kindObject");
+    case "array":
+      return t("jsonEditor.kindArray");
+    case "string":
+      return t("jsonEditor.kindString");
+    case "number":
+      return t("jsonEditor.kindNumber");
+    case "boolean":
+      return t("jsonEditor.kindBoolean");
+    default:
+      return t("jsonEditor.kindNull");
+  }
+}

package/src/components/molecules/json-editor/json-editor.index.ts

@@ -0,0 +1,2 @@
+export { default as ITJSONEditor } from "./json-editor";
+export type { ITJSONEditorProps } from "./json-editor.props";

package/src/components/molecules/json-editor/json-editor.props.ts

@@ -0,0 +1,82 @@
+import type { ReactNode } from "react";
+
+/**
+ * Modo de presentación del documento.
+ *
+ * - `"text"`: editor de código con resaltado, gutter y plegado.
+ * - `"tree"`: árbol navegable de solo lectura sobre el mismo JSON.
+ */
+export type ITJSONEditorMode = "text" | "tree";
+
+/** Paleta del lienzo de código. */
+export type ITJSONEditorTheme = "ink" | "light";
+
+/**
+ * Props de `ITJSONEditor`.
+ *
+ * @example
+ * ```tsx
+ * <ITJSONEditor value={json} onChange={setJson} height={420} mode="text" />
+ * ```
+ */
+export interface ITJSONEditorProps {
+  /** Documento JSON como cadena. Si es `undefined`, el editor arranca vacío. @default "" */
+  value?: string;
+  /** Se dispara con el texto completo cada vez que cambia (teclado, pegado o barra de acciones). */
+  onChange?: (value: string) => void;
+  /** Se dispara tras cada validación con el valor parseado y su estado. */
+  onParse?: (parsed: unknown, isValid: boolean, error?: string) => void;
+  /** Texto de ayuda que se muestra cuando el documento está vacío. */
+  placeholder?: string;
+  /** Bloquea la edición: desaparecen las acciones que modifican el texto. @default false */
+  readOnly?: boolean;
+  /** Modo inicial: `"text"` (código) o `"tree"` (árbol navegable). @default "text" */
+  mode?: ITJSONEditorMode;
+  /** Permite alternar entre texto y árbol desde la barra. @default true */
+  showModeSwitch?: boolean;
+  /** Muestra la barra superior de acciones. @default true */
+  showToolbar?: boolean;
+  /** Muestra el indicador de válido/ inválido con línea y columna del error. @default true */
+  showValidation?: boolean;
+  /** Estadísticas del pie: líneas, nodos, profundidad y tamaño. @default true */
+  showStatusBar?: boolean;
+  /** Muestra los números de línea del gutter. @default true */
+  showLineNumbers?: boolean;
+  /** Muestra el gutter de plegado de bloques `{…}` / `[…]`. @default true */
+  showFoldGutter?: boolean;
+  /** Habilita las acciones de la barra (formatear, minificar, ordenar, escapar). @default true */
+  showTransformActions?: boolean;
+  /** Habilita el botón de copiar el documento completo. @default true */
+  showCopyButton?: boolean;
+  /** Habilita la carga de un `.json` desde disco. @default true */
+  showImportButton?: boolean;
+  /** Habilita la descarga del documento como `.json`. @default true */
+  showDownloadButton?: boolean;
+  /** Muestra la fila de ajustes de vista (ajuste de línea, números, plegado, indentación). @default true */
+  showViewSettings?: boolean;
+  /** Espacios por nivel de indentación, entre 0 y 8. @default 2 */
+  indentSize?: number;
+  /** Ajusta las líneas largas al ancho del editor. Desactivado mantiene el scroll horizontal y el gutter sincronizado. @default false */
+  wrapLines?: boolean;
+  /** Ofrece números de línea y plegado también en la vista de árbol. @default false */
+  treeShowLines?: boolean;
+  /** Paleta del lienzo: `"ink"` (tinta oscura, por defecto) o `"light"`. @default "ink" */
+  canvasTheme?: ITJSONEditorTheme;
+  /** Altura del área de edición: número en píxeles o cualquier medida CSS. @default 340 */
+  height?: number | string;
+  /** Ancho mínimo del editor. Útil dentro de layouts que comprimen. */
+  minWidth?: number | string;
+  /** Acciones extra que se añaden al final de la barra, antes de copiar/descargar. */
+  actions?: ReactNode;
+  /** Clases para el contenedor raíz. */
+  className?: string;
+  /** Identificador HTML del contenedor raíz, para anclarlo desde fuera o en pruebas. */
+  id?: string;
+  /** Clases para el `<textarea>`, por si hay que afinar la tipografía. */
+  textareaClassName?: string;
+  /**
+   * Línea (1-based) que hay que marcar como errónea cuando el fallo lo detecta
+   * la aplicación y no el propio editor.
+   */
+  errorLine?: number;
+}