@axzydev/axzy_ui_system 1.5.0 → 1.5.2

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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/dev.css

@@ -116,19 +116,3 @@ html {
     animation: none;
   }
 }
-
-/* ──────────────────────────────────────────────
-   PANEL DE PROPIEDADES A ANCHO COMPLETO (dev.css)
-   Cuando la vitrina ocupa las 12 columnas, las filas `justify-between` de los
-   controles dejaban la etiqueta a un lado y el control a 800px del otro. Aquí
-   el control se agrupa junto a su etiqueta.
-   ────────────────────────────────────────────── */
-.it-panel-ancho .justify-between {
-  justify-content: flex-start;
-  gap: 0.75rem;
-}
-
-/* Las notas del panel no se estiran a 100+ caracteres por línea. */
-.it-panel-ancho p {
-  max-width: 72ch;
-}

package/src/sandbox/i18n.ts

@@ -72,6 +72,11 @@ export const sandboxMessages: ITMessagesByLocale = {
     "showcase.layout.docs": "Documentación",
     "showcase.layout.eyebrow": "Vitrina de componentes",
     "showcase.layout.gallery": "Variaciones y estados (Galería)",
+    "showcase.layout.galleryTitle": "Variaciones y estados",
+    "showcase.layout.viewCode": "Código",
+    "showcase.layout.hideCode": "Ocultar",
+    "showcase.layout.controls": "Controles",
+    "showcase.layout.api": "API del componente",
     "showcase.layout.jsxCode": "Código JSX",
     "showcase.layout.notes": "Notas",
     "showcase.layout.overview": "Descripción general",
@@ -1013,6 +1018,11 @@ export const sandboxMessages: ITMessagesByLocale = {
     "showcase.layout.docs": "Docs",
     "showcase.layout.eyebrow": "Component showcase",
     "showcase.layout.gallery": "Variations & States (Gallery)",
+    "showcase.layout.galleryTitle": "Variations & states",
+    "showcase.layout.viewCode": "Code",
+    "showcase.layout.hideCode": "Hide",
+    "showcase.layout.controls": "Controls",
+    "showcase.layout.api": "Component API",
     "showcase.layout.jsxCode": "JSX Code",
     "showcase.layout.notes": "Notes",
     "showcase.layout.overview": "Overview",

package/src/sandbox/ui.tsx

@@ -13,7 +13,7 @@
  */
 
 import { useState, type ReactNode } from "react";
-import { FaCheck, FaCopy } from "react-icons/fa";
+import { FaCheck, FaCode, FaCopy } from "react-icons/fa";
 import { useITTranslation } from "@/i18n";
 
 /** Eyebrow mono apagado: encabezados de sección y etiquetas de metadato. */
@@ -367,6 +367,7 @@ export const BloqueCodigo = ({
       />
     </div>
     <pre
+      tabIndex={0}
       className={`overflow-x-auto whitespace-pre-wrap p-4 font-mono text-xs leading-relaxed text-slate-200 ${
         compact ? "max-h-[420px] overflow-y-auto" : ""
       }`}
@@ -375,3 +376,99 @@ export const BloqueCodigo = ({
     </pre>
   </div>
 );
+
+/** Props de `EjemploContenedor`. */
+export interface EjemploContenedorProps {
+  /** Número del ejemplo (`01`, `02`…). Opcional. */
+  numero?: string;
+  /** Título del ejemplo (mono, mayúsculas). */
+  titulo: string;
+  /** El demo. */
+  children: ReactNode;
+  /** Código fuente del ejemplo: si se pasa, aparece el botón «Código». */
+  codigo?: string;
+  /** Nota al pie, bajo el demo. */
+  nota?: string;
+  /** Superficie del demo sin padding (layouts completos). */
+  sangrado?: boolean;
+  /** Clases extra de la superficie del demo. */
+  className?: string;
+}
+
+/**
+ * Contenedor de un ejemplo del sandbox: cabecera con número, título y la acción
+ * de ver el código (siempre visible), superficie del demo y nota opcional. El
+ * código se despliega **dentro** del mismo contenedor, no en una pestaña aparte.
+ *
+ * @example
+ * ```tsx
+ * <EjemploContenedor numero="01" titulo="Con icono" codigo={code}>
+ *   <ITButton icon={<FaSave />}>Guardar</ITButton>
+ * </EjemploContenedor>
+ * ```
+ */
+export const EjemploContenedor = ({
+  numero,
+  titulo,
+  children,
+  codigo,
+  nota,
+  sangrado = false,
+  className = "",
+}: EjemploContenedorProps) => {
+  const { t } = useITTranslation();
+  const [verCodigo, setVerCodigo] = useState(false);
+
+  return (
+    <section className={`overflow-hidden rounded-[10px] border ${FILETE}`}>
+      <header
+        className={`flex flex-wrap items-center gap-x-3 gap-y-2 border-b bg-slate-50/70 px-4 py-2.5 dark:bg-slate-950/40 ${FILETE}`}
+      >
+        {numero && (
+          <span className="font-mono text-[10px] tabular-nums text-slate-400 dark:text-slate-500">
+            {numero}
+          </span>
+        )}
+        <h2 className="min-w-0 flex-1 truncate font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:text-slate-200">
+          {titulo}
+        </h2>
+
+        {codigo && (
+          <button
+            type="button"
+            onClick={() => setVerCodigo(!verCodigo)}
+            aria-expanded={verCodigo}
+            className={`inline-flex items-center gap-1.5 rounded-[8px] border px-2.5 py-1 font-mono text-[10px] uppercase tracking-[0.12em] transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/60 ${
+              verCodigo
+                ? "border-primary-700 text-primary-700 dark:border-primary-500 dark:text-primary-500"
+                : "border-slate-200 text-slate-500 hover:text-slate-900 dark:border-slate-700 dark:text-slate-400 dark:hover:text-white"
+            }`}
+          >
+            <FaCode size={10} />
+            {verCodigo ? t("showcase.layout.hideCode") : t("showcase.layout.viewCode")}
+          </button>
+        )}
+      </header>
+
+      <div
+        className={`bg-white dark:bg-slate-950 ${sangrado ? "" : "p-5 sm:p-6"} ${className}`}
+      >
+        {children}
+      </div>
+
+      {nota && (
+        <p
+          className={`border-t px-4 py-2.5 font-mono text-[11px] leading-relaxed text-slate-500 dark:text-slate-400 ${FILETE}`}
+        >
+          {nota}
+        </p>
+      )}
+
+      {codigo && verCodigo && (
+        <div className={`border-t p-3 ${FILETE}`}>
+          <BloqueCodigo code={codigo} compact />
+        </div>
+      )}
+    </section>
+  );
+};

package/src/showcases/DataShowcases.tsx

@@ -418,7 +418,7 @@ export const TableShowcase = () => {
       gallery={
         <div className="space-y-6">
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryCustomCardsHover")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryCustomCardsHover")}</h3>
             <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
               {TABLE_DATA.slice(0, 4).map((row, i) => {
                 const initials = (row.name as string).split(" ").map((w: string) => w[0]).join("");
@@ -455,7 +455,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryDefaultCards")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryDefaultCards")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={columns}
@@ -469,7 +469,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryCustomCardsPagination")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryCustomCardsPagination")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={columns}
@@ -501,7 +501,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryCompactFixed")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryCompactFixed")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800" style={{ maxWidth: 560 }}>
               <ITTable
                 columns={fixedColumns}
@@ -515,7 +515,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryPinnedNameActions")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryPinnedNameActions")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800" style={{ maxWidth: 520 }}>
               <ITTable
                 columns={pinnedColumns}
@@ -532,7 +532,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryAutoCards")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryAutoCards")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800" style={{ maxWidth: 420 }}>
               <ITTable
                 columns={columns}
@@ -545,7 +545,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryVirtualized")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryVirtualized")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={virtualColumns}
@@ -563,7 +563,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryColumnFilters")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryColumnFilters")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={filterDemoColumns}
@@ -579,7 +579,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryDesignOverrides")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryDesignOverrides")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={columns}
@@ -609,7 +609,7 @@ export const TableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryPerColumnDesign")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryPerColumnDesign")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITTable
                 columns={columns.map((col: any) =>
@@ -1062,7 +1062,7 @@ export const DataTableShowcase = () => {
       gallery={
         <div className="space-y-6">
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryCustomCardsHover")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryCustomCardsHover")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <GalleryDataTable
                 title={t("showcase.data.teamMembers")}
@@ -1105,7 +1105,7 @@ export const DataTableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryDefaultCardsPagination")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryDefaultCardsPagination")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <GalleryDataTable
                 size="sm"
@@ -1116,7 +1116,7 @@ export const DataTableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryDesignOverrides")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryDesignOverrides")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITDataTable
                 columns={userColumns}
@@ -1140,7 +1140,7 @@ export const DataTableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryPinnedIdActive")}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryPinnedIdActive")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800" style={{ maxWidth: 520 }}>
               <ITDataTable
                 columns={pinnedColumns}
@@ -1158,7 +1158,7 @@ export const DataTableShowcase = () => {
           </div>
 
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.data.galleryServerVirtualization", { page: dtVirtualized ? 200 : 10 })}</h3>
+            <h3 className="mb-3 w-fit border-l-2 border-primary-700 pl-2.5 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-700 dark:border-primary-500 dark:text-slate-200">{t("showcase.data.galleryServerVirtualization", { page: dtVirtualized ? 200 : 10 })}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITDataTable
                 key={dtVirtualized ? "dt-virt-on" : "dt-virt-off"}
@@ -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.",
+        ],
+      }}
     />
   );
 };