@axzydev/axzy_ui_system 1.5.1 → 1.5.3

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "type": "module",
   "sideEffects": [
     "*.css"
@@ -42,7 +42,9 @@
     "ext:build": "node vscode-extension/esbuild.mjs",
     "ext:typecheck": "tsc --noEmit -p vscode-extension/tsconfig.json",
     "ext:package": "node vscode-extension/esbuild.mjs && cd vscode-extension && npx --yes @vscode/vsce package --no-dependencies",
-    "audit:sandbox": "node scripts/audit-sandbox.mjs"
+    "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"
   },
   "dependencies": {
     "clsx": "^2.1.1",

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

@@ -7,15 +7,15 @@ export interface ITButtonProps {
   label?: string
   /** Custom content to render inside the button. Takes precedence over `label`. */
   children?: React.ReactNode;
-  /** Icon element rendered before the label. */
+  /** Icon element rendered before the label. With `variant="icon-only"` and no `label`/`children` it becomes the only content and is centered in the square button. */
   icon?: React.ReactNode;
   /** Click handler for the button. */
   onClick?: () => void;
   /** Color theme key. Values come from the semantic color palette (e.g. `"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"info"`, `"purple"`, `"error"`, `"gray"`). @default "primary" */
   color?: ColorsTypes;
-  /** Button size. Valid values: `"sm"`, `"md"`, `"lg"`. @default "md" */
+  /** Button size. Valid values: `"sm"`, `"md"`, `"lg"`. In `variant="icon-only"` it also scales the square padding (`buttonIconPadding`: `sm` 0.5rem, `md` 0.625rem, `lg` 0.75rem). @default "md" */
   size?: SizesTypes;
-  /** Button visual style. Valid values: `"filled"`, `"outlined"`, `"raised"`, `"rounded"`, `"text"`, `"raised-text"`, `"icon-only"`, `"link"`. @default "filled" */
+  /** Button visual style. Valid values: `"filled"`, `"outlined"`, `"raised"`, `"rounded"`, `"text"`, `"raised-text"`, `"icon-only"`, `"link"`. `"icon-only"` renders a centered square icon button; combine it with `icon` and `ariaLabel`. @default "filled" */
   variant?: keyof typeof buttonVariants;
   /** Disables the button interaction and applies reduced opacity. @default false */
   disabled?: boolean;

package/src/components/atoms/button/button.tsx

@@ -1,4 +1,6 @@
 import {
+  buttonIconPadding,
+  buttonIconSizes,
   buttonSizes,
   buttonVariants,
 } from "@/types/button.types";
@@ -35,6 +37,16 @@ export default function ITButton({
 }: ITButtonProps) {
   const [isHovered, setIsHovered] = useState(false);
   const [isFocused, setIsFocused] = useState(false);
+
+  /** La variante `icon-only` siempre es un cuadrado con padding simétrico. */
+  const isIconOnly = variant === "icon-only";
+
+  /**
+   * Contenido "solo icono": hay `icon` y no hay `children`.
+   * En ese caso NO se envuelve el icono en el wrapper con `gap-1.5` ni en un `ITText` vacío,
+   * que lo desplazaban a la izquierda del centro.
+   */
+  const isIconOnlyContent = isIconOnly && Boolean(icon) && !children;
   
   // Get specific button config from theme
   const themeBtn = theme.button as any;
@@ -64,8 +76,11 @@ export default function ITButton({
       style.borderRadius = "9999px";
     }
 
-    if (variant === "icon-only") {
-      style.padding = "0.5rem"; // Square padding override
+    if (isIconOnly) {
+      // Padding simétrico explícito: con `aspect-square` define un cuadrado exacto
+      // y evita que las utilidades `px-*`/`py-*` de `buttonSizes` desalineen el icono.
+      style.padding = buttonIconPadding[size] ?? "0.5rem";
+      style.lineHeight = 1;
     }
 
     if (isSolid) {
@@ -103,7 +118,7 @@ export default function ITButton({
         // Apply variant base styles (border, shadow, rounded-full)
         buttonVariants[variant || "filled"],
         // Apply size classes (padding/font-size)
-        buttonSizes[size],
+        isIconOnly ? buttonIconSizes[size] : buttonSizes[size],
         className,
         { "opacity-50 cursor-not-allowed": disabled }
       )}
@@ -118,10 +133,15 @@ export default function ITButton({
       title={title || ariaLabel || label}
     >
       {children || (
-        <span className={clsx("inline-flex items-center gap-1.5 font-semibold", { "opacity-50": disabled })}>
-          {icon && <span className="flex-shrink-0">{icon}</span>}
-          <ITText as="span">{label}</ITText>
-        </span>
+        isIconOnlyContent ? (
+          // Icono solo: sin wrapper con `gap` ni `ITText` vacío, que lo desplazaban a la izquierda.
+          <span className="inline-flex items-center justify-center leading-none">{icon}</span>
+        ) : (
+          <span className={clsx("inline-flex items-center gap-1.5 font-semibold", { "opacity-50": disabled })}>
+            {icon && <span className="flex-shrink-0">{icon}</span>}
+            <ITText as="span">{label}</ITText>
+          </span>
+        )
       )}
     </button>
   );

package/src/sandbox/i18n.ts

@@ -772,6 +772,7 @@ export const sandboxMessages: ITMessagesByLocale = {
     "showcase.forms.clicksRegistered": "Clicks registrados: {count}",
     "showcase.forms.withIcon": "Con Icono",
     "showcase.forms.galleryWithIcon": "Con Icono",
+    "showcase.forms.galleryIconOnly": "Solo Icono (centrado)",
     "showcase.forms.galleryVariants": "Variantes",
     "showcase.forms.gallerySemanticColors": "Colores Semánticos",
     "showcase.forms.sync": "Sincronizar",
@@ -1714,6 +1715,7 @@ export const sandboxMessages: ITMessagesByLocale = {
     "showcase.forms.clicksRegistered": "Clicks registered: {count}",
     "showcase.forms.withIcon": "With icon",
     "showcase.forms.galleryWithIcon": "With icon",
+    "showcase.forms.galleryIconOnly": "Icon only (centered)",
     "showcase.forms.galleryVariants": "Variants",
     "showcase.forms.gallerySemanticColors": "Semantic colors",
     "showcase.forms.sync": "Sync",

package/src/showcases/DataShowcases.tsx

@@ -1309,6 +1309,27 @@ export const BadgetShowcase = () => {
           <ITBadget label="Large" color="primary" size="lg" />
         </div>
       }
+      doc={{
+        summary: "Etiqueta compacta de estado o categoría, con colores del tema y variantes filled/outlined.",
+        examples: [
+          '<ITBadget label="Activo" color="success" />',
+          '<ITBadget label="Pendiente" color="warning" variant="outlined" size="sm" />',
+          '<ITBadget color="danger" size="lg">\n  <span className="flex items-center gap-1">3 nuevos</span>\n</ITBadget>',
+        ],
+        props: [
+          { name: "label", type: "string", description: "Texto mostrado dentro del badge. Se ignora si se pasa children." },
+          { name: "children", type: "ReactNode", description: "Contenido personalizado; tiene prioridad sobre label." },
+          { name: "color", type: "ColorsTypes", default: '"primary"', description: 'Clave de color semántica: "primary", "secondary", "success", "danger", "warning", "info", "purple", "error" o "gray".' },
+          { name: "size", type: '"sm" | "md" | "lg"', default: '"md"', description: "Tamaño del badge (padding y tamaño de fuente)." },
+          { name: "variant", type: '"filled" | "outlined"', default: '"filled"', description: "Estilo visual: fondo sólido del tema o fondo transparente con borde y texto del color." },
+          { name: "className", type: "string", description: "Clases CSS adicionales del elemento." },
+        ],
+        notes: [
+          "Renderiza un <span> inline-flex centrado; la apariencia sale de theme.badge[color] (radio completo, borde de 1px), no de clases Tailwind. Una clave inexistente en el tema cae en la configuración de primary.",
+          "Para color=\"primary\" el color se resuelve con utilidades (primary-700 en claro, primary-500 en oscuro) para que el contraste pase AA; el resto de colores del tema se respetan tal cual.",
+          "No declara role ni atributos ARIA propios: es un span textual/decorativo, no un control.",
+        ],
+      }}
     />
   );
 };
@@ -1349,6 +1370,26 @@ export const ImageShowcase = () => {
           </div>
         </>
       }
+      doc={{
+        summary: "Imagen con fallback automático: si el src principal falla al cargar, muestra la imagen de respaldo.",
+        description: "El tamaño y la forma se controlan por completo desde className; las imágenes internas ocupan el 100% del contenedor con object-cover.",
+        examples: [
+          '<ITImage src="/foto.jpg" alt="Foto de usuario" />',
+          '<ITImage\n  src={user.avatar}\n  alt={user.name}\n  fallback="/placeholder.png"\n  className="h-32 w-32 rounded-full"\n/>',
+          '<ITImage src={logo} alt="Logo" fallback="/logo-fallback.svg" className="h-40 w-full rounded-xl object-cover" />',
+        ],
+        props: [
+          { name: "src", type: "string", required: true, description: "URL de la imagen principal." },
+          { name: "alt", type: "string", description: "Texto alternativo de la imagen principal (accesibilidad)." },
+          { name: "fallback", type: "string", default: '""', description: "URL de la imagen mostrada cuando el src principal dispara onError." },
+          { name: "className", type: "string", default: '""', description: "Clases del contenedor externo; definen el tamaño de la imagen." },
+        ],
+        notes: [
+          "El className se aplica al <div> contenedor (flex items-center justify-center) y las <img> internas usan w-full h-full object-cover: sin alto/ancho en className la imagen no toma tamaño propio.",
+          "El fallback se renderiza con alt fijo traducido (image.fallbackAlt, \"Fallback\") en lugar del alt del componente, y el cambio a fallback es permanente: si el src vuelve a estar disponible hay que remontar el componente.",
+          "No reenvía atributos nativos del <img> (loading, width, height, onClick…): onClick está declarado en las props, pero la implementación actual no lo conecta.",
+        ],
+      }}
     />
   );
 };

package/src/showcases/FeedbackShowcases.tsx

@@ -74,6 +74,28 @@ export const DialogShowcase = () => {
           </div>
         </>
       }
+      doc={{
+        summary: "Modal montado en un portal sobre `document.body` para confirmaciones, formularios o detalle, con cierre por Escape o clic fuera.",
+        description: "Con `title` dibuja una barra propia o un `ITFormHeader` si `useFormHeader` está activo, y con `fullScreen` ocupa todo el viewport.",
+        examples: [
+          '<ITDialog isOpen={open} onClose={() => setOpen(false)} title="Confirmación de auditoría"><p>¿Registrar la auditoría?</p></ITDialog>',
+          '<ITDialog isOpen={open} onClose={close} title="Nuevo usuario" useFormHeader>…</ITDialog>',
+          '<ITDialog isOpen={open} onClose={close} fullScreen><ITDataTable columns={cols} fetchData={api.page} /></ITDialog>',
+        ],
+        props: [
+          { name: "isOpen", type: "boolean", required: true, description: "Controla la visibilidad; con `false` no renderiza nada." },
+          { name: "onClose", type: "() => void", required: true, description: "Se dispara al pulsar Escape, hacer clic fuera del panel o usar el botón de cerrar." },
+          { name: "children", type: "React.ReactNode", required: true, description: "Contenido del cuerpo del diálogo." },
+          { name: "className", type: "string", description: "Clases adicionales del panel; se ignoran en `fullScreen`." },
+          { name: "title", type: "string", description: "Encabezado opcional mostrado en la parte superior." },
+          { name: "useFormHeader", type: "boolean", default: "false", description: "Con `title`, renderiza un `ITFormHeader` en lugar de la barra por defecto." },
+          { name: "fullScreen", type: "boolean", default: "false", description: "Hace que el diálogo ocupe todo el viewport (sin radio, borde ni sombra)." },
+        ],
+        notes: [
+          "Los paneles flotantes que abre su contenido (selects, pickers, menús) viven en su propio portal, así que elegir una opción no cierra el diálogo.",
+          "No trae `role=\"dialog\"`, `aria-modal`, focus trap ni retorno de foco: esa gestión queda en el consumidor.",
+        ],
+      }}
     />
   );
 };
@@ -130,6 +152,24 @@ export const ToastShowcase = () => {
           <ITButton label={t("showcase.feedback.toastInfo")} color="info" size="sm" onClick={() => { setMsg(t("showcase.feedback.msgInfo")); setType("info"); setVisible(true); }} />
         </div>
       }
+      doc={{
+        summary: "Notificación flotante que se autocierra y colorea según su severidad, colocada en una de seis posiciones.",
+        examples: [
+          '<ITToast message="Cambios guardados" type="success" duration={2000} position="bottom-right" onClose={() => setVisible(false)} />',
+          '<ITToast message="No se pudo conectar" type="error" />',
+        ],
+        props: [
+          { name: "message", type: "string", required: true, description: "Texto que muestra el toast." },
+          { name: "type", type: '"success" | "error" | "warning" | "info" | "primary" | "danger" | string', default: '"info"', description: "Severidad; define el icono y el color de fondo." },
+          { name: "duration", type: "number", default: "1500", description: "Milisegundos antes del autocierre." },
+          { name: "position", type: '"top-right" | "top-center" | "top-left" | "bottom-right" | "bottom-center" | "bottom-left"', default: '"top-right"', description: "Posición fija en pantalla." },
+          { name: "onClose", type: "() => void", description: "Se invoca 300 ms después del autocierre o del cierre manual, al terminar la transición." },
+        ],
+        notes: [
+          "`type` acepta cualquier string: se resuelve contra `theme.colors`; si la clave no existe, cae al `primary[500]` del tema.",
+          "El contenedor lleva `role=\"alert\"`, `fixed z-[80]` y un ancho mínimo de 300 px. Sin `onClose` el toast se desvanece igual, pero el padre no puede desmontarlo.",
+        ],
+      }}
     />
   );
 };
@@ -204,6 +244,25 @@ export const LoaderShowcase = () => {
           <ITLoader variant="pulse" size="md" color="purple" />
         </div>
       }
+      doc={{
+        summary: "Indicador de carga con cuatro animaciones (spinner, dots, bar y pulse) y color semántico del tema o valor CSS.",
+        examples: [
+          '<ITLoader variant="spinner" size="md" color="primary" />',
+          '<ITLoader variant="dots" size="sm" color="success" />',
+          '<div className="w-48"><ITLoader variant="bar" color="#06b6d4" /></div>',
+        ],
+        props: [
+          { name: "size", type: '"sm" | "md" | "lg" | "xl"', default: '"md"', description: "Tamaño del indicador." },
+          { name: "variant", type: '"spinner" | "dots" | "bar" | "pulse"', default: '"spinner"', description: "Tipo de animación." },
+          { name: "color", type: "string", default: '"primary"', description: "Clave semántica del tema, valor CSS (`#rrggbb`, `rgb(...)`) o clase CSS por compatibilidad." },
+          { name: "className", type: "string", default: '""', description: "Clases adicionales (en `bar` define el ancho)." },
+        ],
+        notes: [
+          "Resolución de color: si es clave de `theme.colors` usa el tono 500; si empieza por `#` o `rgb` lo usa tal cual; cualquier otro string se inyecta como clase.",
+          "`spinner` lleva `role=\"status\"` con un texto oculto para lectores de pantalla; `bar` ocupa todo el ancho de su contenedor, así que conviene acotarlo con `className`.",
+          "En `dots` el tamaño se deriva quitando la primera `l`/`g` a `size`, por lo que solo `sm` y `md` producen clases válidas.",
+        ],
+      }}
     />
   );
 };
@@ -285,6 +344,29 @@ export const ThemeProviderShowcase = () => {
           </p>
         </ITStack>
       }
+      doc={{
+        summary: "Provider raíz del tema: inyecta las variables CSS de color, resuelve el modo claro/oscuro y aplica densidad, radio y sombras globales.",
+        description: "Envuelve la app (o la parte que usa componentes AXZY) una sola vez. Expone `useITTheme()` con `palette`, `colors`, `setPalette`, `updateColor`, `resetTheme`, `applyPreset`, `resolvedTheme`, `darkModeMode`, `setDarkModeMode` y `appearance`, y opcionalmente un FAB con diseñador de temas en vivo.",
+        examples: [
+          '<ITThemeProvider><App /></ITThemeProvider>',
+          '<ITThemeProvider theme={{ primary: "#3b82f6", layout: { sidebarBg: "#0f172a" } }} showFab={false}><App /></ITThemeProvider>',
+          '<ITThemeProvider density={0.9} radius={8} shadow={1} appearance="flat"><App /></ITThemeProvider>',
+        ],
+        props: [
+          { name: "theme", type: "Partial<ITThemePalette>", description: "Overrides de paleta fusionados (deep merge) con el tema por defecto: `primary`, `secondary`, `ternary`, `danger`, `success`, `info`, `alert`, `warning`, `layout` y `table`." },
+          { name: "children", type: "React.ReactNode", required: true, description: "Subárbol que recibe el contexto y las variables CSS." },
+          { name: "showFab", type: "boolean", default: "true", description: "Muestra el botón flotante que abre el diseñador de temas y persiste la paleta; en producción se suele poner en `false`." },
+          { name: "density", type: "number", default: "1", description: "Factor de densidad global: escala el `font-size` raíz para compactar todo lo basado en `rem`. Se limita a `0.5`–`1.5`." },
+          { name: "radius", type: "number", default: "—", description: "Radio global en px aplicado a toda la escala `--radius-*`; `0` deja las esquinas totalmente cuadradas." },
+          { name: "shadow", type: "number", default: "—", description: "Fuerza global de sombras: `0` ninguna, `1` sutiles, `2` look actual, `3` marcadas." },
+          { name: "appearance", type: '"soft" | "flat"', default: '"soft"', description: "Lenguaje visual del sistema; `\"flat\"` usa superficies planas con bordes de 1 px y fija `data-it-appearance` en `<html>`." },
+        ],
+        notes: [
+          "`useITTheme()` lanza error si se usa fuera del provider; `useITThemeSafe()` devuelve `undefined` en ese caso.",
+          "Con `showFab` la paleta, el modo y los presets se persisten en `localStorage` (`it-theme-palette`, `it-theme-dark-mode`, `it-theme-custom-presets`); con `showFab={false}` el estado se sincroniza con la prop `theme`.",
+          "`radius={0}` no significa «sin override»: deja todas las esquinas cuadradas. Para no tocar la escala hay que omitir la prop.",
+        ],
+      }}
     />
   );
 };