@axzydev/axzy_ui_system 1.5.1 → 1.5.2

package/src/showcases/LayoutPrimitivesShowcases.tsx

@@ -669,6 +669,37 @@ export const FlexShowcase = () => {
       title="ITFlex"
       description={t("showcase.layoutPrimitives.flexDesc")}
       code={buildCode()}
+      doc={{
+        summary:
+          "Contenedor flexbox completo: dirección, alineación, distribución, wrap y factores flex (grow/shrink/basis) en un solo componente.",
+        description:
+          "Es el primitivo de layout con más control; úsalo cuando ITStack no llegue (reparto por ejes, hijos que crecen o se encogen, wrap con alineación). La separación se mide en unidades de 0.25rem y se emite como `gap`.",
+        examples: [
+          '<ITFlex justify="between" align="center" gap={3}>\n  <h2>Panel</h2>\n  <ITButton label="Exportar" variant="outlined" />\n</ITFlex>',
+          '<ITFlex direction="column" gap={2} as="section">\n  <header>Título</header>\n  <main>Contenido</main>\n</ITFlex>',
+          '<ITFlex gap={2}>\n  <ITFlex grow basis={56}>Contenido flexible</ITFlex>\n  <span>Fijo</span>\n</ITFlex>',
+        ],
+        props: [
+          { name: "children", type: "ReactNode", description: "Elementos hijos del contenedor." },
+          { name: "direction", type: '"row" | "column" | "row-reverse" | "column-reverse"', default: '"row"', description: "Dirección del eje principal." },
+          { name: "align", type: '"start" | "end" | "center" | "stretch" | "baseline"', description: "Alineación en el eje transversal." },
+          { name: "justify", type: '"start" | "end" | "center" | "between" | "around" | "evenly"', description: "Reparto de los hijos en el eje principal." },
+          { name: "wrap", type: '"nowrap" | "wrap" | "wrap-reverse"', description: "Si los hijos saltan a la siguiente línea." },
+          { name: "gap", type: "number", default: "0", description: "Separación entre hijos en unidades de 0.25rem." },
+          { name: "grow", type: "boolean | number", description: "Factor flex-grow: `true` = 1, `false` = 0, un número se usa tal cual." },
+          { name: "shrink", type: "boolean | number", description: "Factor flex-shrink: `true` = 1, `false` = 0, un número se usa tal cual." },
+          { name: "basis", type: "string | number", description: "flex-basis: los números se multiplican por 0.25rem, los strings se usan tal cual." },
+          { name: "className", type: "string", description: "Clases CSS adicionales." },
+          { name: "style", type: "CSSProperties", description: "Estilos inline; se aplican después de gap/grow/shrink/basis, así que pueden sobrescribirlos." },
+          { name: "as", type: "ElementType", default: '"div"', description: "Elemento HTML a renderizar en lugar del `div` por defecto." },
+          { name: "onClick", type: "(e: React.MouseEvent) => void", description: "Handler de click del contenedor." },
+        ],
+        notes: [
+          "gap, grow, shrink y basis se resuelven como estilos inline, no como clases Tailwind: el `style` propio tiene la última palabra.",
+          "align, justify y wrap no traen valor por defecto: si se omiten no se emite clase y valen los valores iniciales de CSS (stretch, flex-start, nowrap).",
+          "El contenedor siempre es `display: flex`; para una sola dirección con separación uniforme, ITStack es más corto.",
+        ],
+      }}
       demo={
         <div className="w-full max-w-xl flex flex-col">
           <div className="min-h-[360px]">
@@ -939,6 +970,37 @@ export const GridShowcase = () => {
       title="ITGrid"
       description={t("showcase.layoutPrimitives.gridDesc")}
       code={buildCode()}
+      doc={{
+        summary:
+          "Sistema de grid CSS responsivo de 12 columnas con el patrón container/item: el contenedor fija columnas y gap, y cada item declara su span por breakpoint.",
+        description:
+          "Como `container` renderiza `display: grid` con `grid-cols-{columns}`; como `item` calcula el `col-span` base y los spans de sm/md/lg/xl. Si no se pasa ninguno de los dos, renderiza un `div` normal.",
+        examples: [
+          '<ITGrid container spacing={4}>\n  <ITGrid item xs={12} md={6}>Sidebar</ITGrid>\n  <ITGrid item xs={12} md={6}>Contenido</ITGrid>\n</ITGrid>',
+          '<ITGrid container columns={3} spacing={2}>\n  {plans.map((plan) => (\n    <ITGrid key={plan.id} item>{plan.name}</ITGrid>\n  ))}\n</ITGrid>',
+          '<ITGrid container spacing={4} as="section">\n  <ITGrid item xs={12} lg={8}>Gráfico</ITGrid>\n  <ITGrid item xs={12} lg={4}>Actividad</ITGrid>\n</ITGrid>',
+        ],
+        props: [
+          { name: "children", type: "ReactNode", description: "Elementos hijos." },
+          { name: "container", type: "boolean", description: "Renderiza el padre: `display: grid` + `grid-cols-{columns}`." },
+          { name: "item", type: "boolean", description: "Renderiza un hijo con `col-span` según los breakpoints. Si `container` también está activo, gana `container`." },
+          { name: "spacing", type: "number", default: "0", description: "Gap entre hijos en unidades de 0.25rem; solo aplica con `container` y si es mayor que 0." },
+          { name: "columns", type: "number", default: "12", description: "Columnas del contenedor (se acota a 1–12); también limita el span de los items." },
+          { name: "xs", type: "number", description: "Span en el breakpoint base; si falta se usa `sm` y, si tampoco hay, el item ocupa todo (`col-span-full`)." },
+          { name: "sm", type: "number", description: "Span a partir del breakpoint `sm`." },
+          { name: "md", type: "number", description: "Span a partir del breakpoint `md`." },
+          { name: "lg", type: "number", description: "Span a partir del breakpoint `lg`." },
+          { name: "xl", type: "number", description: "Span a partir del breakpoint `xl`." },
+          { name: "className", type: "string", description: "Clases CSS adicionales." },
+          { name: "style", type: "CSSProperties", description: "Estilos inline." },
+          { name: "as", type: "ElementType", default: '"div"', description: "Elemento HTML a renderizar en lugar del `div` por defecto." },
+        ],
+        notes: [
+          "El span base es `xs ?? sm` y, si no se define ninguno, cae en `col-span-full` (las 12 columnas).",
+          "Los spans se redondean y se acotan entre 1 y `columns`: con 3 columnas, `md={99}` acaba en `md:col-span-3`.",
+          "Tailwind no ve clases construidas en runtime: `grid-cols-{n}` y `col-span-{n}` están en el safelist `@source inline(...)` de src/index.css.",
+        ],
+      }}
       demo={
         <div className="w-full max-w-xl flex flex-col">
           <div className="min-h-[360px]">
@@ -1351,6 +1413,30 @@ export const GridShowcase = () => {
       title={t("showcase.layoutPrimitives.screensTitle")}
       description={t("showcase.layoutPrimitives.screensSubtitle")}
       code={code}
+      doc={{
+        summary:
+          "Receta de pantalla: un dashboard de una columna que compone ITStack, ITFlex, ITGrid, ITStatCard, ITAvatar e ITButton para armar cabecera, KPIs y bloque de gráfico + actividad.",
+        description:
+          "No es un componente de la librería, sino un patrón de composición: primero la cabecera con su acción, después la fila de métricas y por último el contenido a dos columnas, apilado en móvil.",
+        examples: [
+          '<ITGrid container spacing={3}>\n  <ITGrid item xs={12} sm={6} lg={3}>\n    <ITStatCard label="Usuarios activos" value="1,245" trend="+12%" trendDirection="up" />\n  </ITGrid>\n</ITGrid>',
+          '<ITFlex gap={3} align="center">\n  <ITAvatar initials="AL" size="sm" color="bg-primary-500" />\n  <p>Ana López creó un reporte</p>\n</ITFlex>',
+        ],
+        props: [
+          { name: "ITStack", type: "componente", description: "Columna raíz (`spacing={6}`) que separa cabecera, métricas y gráficos." },
+          { name: "ITFlex", type: "componente", description: "Cabecera con `justify=\"between\" align=\"center\"` y cada fila de actividad con `gap={3} align=\"center\"`." },
+          { name: "ITGrid (container)", type: "componente", description: "Rejilla de 12 columnas (`spacing={3}`) para la fila de KPIs y para el bloque de gráfico/actividad." },
+          { name: "ITGrid (item)", type: "componente", description: "Reparto responsive: `xs={12} sm={6} lg={3}` en las métricas y `xs={12} lg={8}` / `lg={4}` en el contenido." },
+          { name: "ITStatCard", type: "componente", description: "Cada KPI, con `label`, `value`, `trend`, `trendDirection` y `color` para el fondo." },
+          { name: "ITAvatar", type: "componente", description: "Iniciales del usuario en la actividad reciente, con `size=\"sm\"` y `color`." },
+          { name: "ITButton", type: "componente", description: "Acción de la cabecera (“Exportar”), con `variant=\"outlined\" size=\"sm\"`." },
+        ],
+        notes: [
+          "Es una receta, no un componente: no tiene props propias; en la tabla se documentan las piezas que la componen.",
+          "Criterio de composición: cabecera → KPIs en 4 columnas (`lg={3}`) → contenido 8/4 (`lg={8}` + `lg={4}`); todo a ancho completo por debajo de `sm` y `lg`.",
+          "El demo usa `demoMinAncho={780}` y textos de `useITTranslation()`; los colores salen de tokens (`bg-primary-500`), no de valores sueltos.",
+        ],
+      }}
       demo={
         <div className="w-full">
           <p className="mb-4 font-mono text-[11px] uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">
@@ -1462,6 +1548,30 @@ export const ScreenFormShowcase = () => {
       title={t("showcase.layoutPrimitives.screensTitle")}
       description={t("showcase.layoutPrimitives.screensSubtitle")}
       code={formCode}
+      doc={{
+        summary:
+          "Receta de pantalla: un formulario responsive que compone ITStack, ITGrid, ITInput, ITSelect, ITFlex e ITButton para armar encabezado, campos y barra de acciones.",
+        description:
+          "Tampoco es un componente: es el patrón de un formulario controlado dentro de una tarjeta. La rejilla de 12 columnas coloca los campos cortos en pareja y los largos a fila completa.",
+        examples: [
+          '<ITGrid container spacing={4}>\n  <ITGrid item xs={12} md={6}>\n    <ITInput name="nombre" label="Nombre" onChange={() => {}} />\n  </ITGrid>\n  <ITGrid item xs={12}>\n    <ITInput name="email" label="Email" onChange={() => {}} />\n  </ITGrid>\n</ITGrid>',
+          '<ITFlex justify="end" gap={3}>\n  <ITButton label="Cancelar" variant="outlined" size="sm" />\n  <ITButton label="Guardar" size="sm" />\n</ITFlex>',
+        ],
+        props: [
+          { name: "ITStack", type: "componente", description: "Columna raíz (`spacing={6}`) que separa el encabezado de la rejilla de campos." },
+          { name: "ITGrid (container)", type: "componente", description: "Rejilla de 12 columnas con `spacing={4}` para repartir los campos." },
+          { name: "ITGrid (item)", type: "componente", description: "`xs={12} md={6}` para los campos en pareja y `xs={12}` para los largos (email) y la fila de botones." },
+          { name: "ITInput", type: "componente", description: "Campos de texto controlados con `name`, `label`, `placeholder` y `onChange`." },
+          { name: "ITSelect", type: "componente", description: "Listas de opciones con `name`, `label` y `options` (`{ label, value }`)." },
+          { name: "ITFlex", type: "componente", description: "Barra de acciones alineada a la derecha (`justify=\"end\" gap={3}`)." },
+          { name: "ITButton", type: "componente", description: "“Cancelar” (`variant=\"outlined\"`) y “Guardar”; ambos con `size=\"sm\"`." },
+        ],
+        notes: [
+          "Es una receta de composición: las props de la tabla son las piezas que usa, no una API propia.",
+          "Formulario controlado: cada ITInput/ITSelect recibe `name` y `onChange`; ITInput los exige, aunque en el ejemplo el handler sea un no-op.",
+          "Mismo criterio responsive que el dashboard: 1 columna en móvil (`xs={12}`) y 2 a partir de `md` (`md={6}`), con las acciones a ancho completo al final.",
+        ],
+      }}
       demo={
         <div className="w-full">
           <p className="mb-4 font-mono text-[11px] uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">

package/src/showcases/NavigationShowcases.tsx

@@ -65,6 +65,26 @@ export const TabsShowcase = () => {
           />
         </>
       }
+      doc={{
+        summary:
+          "Navegación por pestañas con dos variantes visuales (`line` y `pill`) que gestiona internamente cuál está activa.",
+        examples: [
+          '<ITTabs items={[{ id: "general", label: "General", content: <GeneralPanel /> }]} />',
+          '<ITTabs variant="pill" defaultActiveId="security" onChange={setActive} items={tabs} />',
+        ],
+        props: [
+          { name: "items", type: "ITTabItem[]", required: true, description: "Pestañas a renderizar: { id, label, content, icon?, disabled? }." },
+          { name: "defaultActiveId", type: "string", default: "primer item", description: "`id` de la pestaña activa al montar." },
+          { name: "onChange", type: "(id: string) => void", description: "Se dispara al cambiar de pestaña, con el nuevo `id`." },
+          { name: "variant", type: '"line" | "pill"', default: '"line"', description: "`line` = indicador inferior; `pill` = fondo redondeado." },
+          { name: "className", type: "string", default: '""', description: "Clases adicionales de la fila de pestañas." },
+          { name: "containerClassName", type: "string", default: '""', description: "Clases adicionales del contenedor externo." },
+        ],
+        notes: [
+          "Estado no controlado: no existe `activeId`; si el `id` activo desaparece de `items`, el contenido queda vacío.",
+          'Los botones son `<button>` nativos, pero sin roles de pestañas (`role="tab"`, `aria-selected`) ni navegación con flechas.',
+        ],
+      }}
     />
   );
 };
@@ -115,6 +135,35 @@ export const StepperShowcase = () => {
           </div>
         </>
       }
+      doc={{
+        summary:
+          "Asistente paso a paso (wizard) con indicador de progreso, panel de contenido y botones Atrás / Siguiente (Finalizar en el último paso).",
+        description:
+          "El paso activo es controlado (`currentStep`): cada paso define su propio contenido y el panel lo monta con transición.",
+        examples: [
+          "<ITStepper steps={steps} currentStep={step} onStepChange={setStep} onFinish={save} />",
+          '<ITStepper steps={steps} currentStep={0} useIcons scrollableContent maxContentHeight="320px" />',
+        ],
+        props: [
+          { name: "steps", type: "Step[]", required: true, description: "Pasos del flujo: { label, content, icon? }." },
+          { name: "currentStep", type: "number", required: true, description: "Índice base 0 del paso activo." },
+          { name: "onFinish", type: "() => void", description: "Se llama al pulsar «Finalizar» en el último paso." },
+          { name: "onStepChange", type: "(step: number) => void", description: "Se dispara en cada cambio de paso, con el nuevo índice." },
+          { name: "allowClickToJump", type: "boolean", default: "true", description: "Permite saltar a pasos completados o al actual desde sus indicadores." },
+          { name: "useIcons", type: "boolean", default: "false", description: "Muestra el icono de cada paso en lugar del número." },
+          { name: "disableNext", type: "boolean", default: "false", description: "Deshabilita «Siguiente» / «Finalizar»." },
+          { name: "scrollableContent", type: "boolean", default: "false", description: "Hace desplazable el panel de contenido." },
+          { name: "maxContentHeight", type: "string", default: '"400px"', description: "Altura máxima del panel desplazable (valor CSS)." },
+          { name: "color", type: "string", default: '"primary"', description: "Color semántico del tema para paso activo y botones; acepta también un color crudo." },
+          { name: "containerClassName", type: "string", description: "Clases adicionales del contenedor externo." },
+          { name: "stepClassName", type: "string", description: "Clases adicionales del panel de contenido." },
+        ],
+        notes: [
+          "«Atrás» se deshabilita en el primer paso; en el último, «Siguiente» pasa a «Finalizar» y dispara `onFinish`.",
+          "El contador «Paso N de M» se oculta por debajo del breakpoint `sm`.",
+          'El panel usa `role="region"` con `aria-labelledby` y los indicadores `aria-current="step"`.',
+        ],
+      }}
     />
   );
 };
@@ -162,6 +211,32 @@ export const PaginationShowcase = () => {
           />
         </>
       }
+      doc={{
+        summary:
+          "Paginador con anterior/siguiente, números de página (con elipsis si hay muchas) y selector opcional de filas por página.",
+        examples: [
+          "<ITPagination currentPage={page} totalPages={10} onPageChange={setPage} />",
+          '<ITPagination currentPage={page} totalPages={20} onPageChange={setPage} color="secondary" siblingCount={2} />',
+          "<ITPagination currentPage={page} totalPages={20} onPageChange={setPage} itemsPerPageOptions={[10, 25, 50]} itemsPerPage={10} onItemsPerPageChange={setSize} totalItems={95} />",
+        ],
+        props: [
+          { name: "currentPage", type: "number", required: true, description: "Página activa (indexada en 1)." },
+          { name: "totalPages", type: "number", required: true, description: "Número total de páginas." },
+          { name: "onPageChange", type: "(page: number) => void", required: true, description: "Se dispara al pulsar una página o anterior/siguiente." },
+          { name: "siblingCount", type: "number", default: "1", description: "Páginas visibles antes y después de la actual." },
+          { name: "color", type: "string", default: '"primary"', description: "Color semántico del tema (primary, secondary, success, danger, warning, info, purple) o un valor crudo." },
+          { name: "className", type: "string", description: "Clases adicionales del contenedor." },
+          { name: "itemsPerPageOptions", type: "number[]", description: "Opciones del selector de filas por página; activa la variante con resumen." },
+          { name: "itemsPerPage", type: "number", description: "Valor actual de filas por página. Requerido junto a `itemsPerPageOptions`." },
+          { name: "onItemsPerPageChange", type: "(value: number) => void", description: "Se dispara al cambiar las filas por página." },
+          { name: "totalItems", type: "number", description: "Total de elementos; alimenta el resumen «X - Y de Z»." },
+        ],
+        notes: [
+          "Se auto-oculta (devuelve `null`) si `currentPage === 0` o si, sin selector, el rango tiene menos de 2 páginas.",
+          "La variante con `itemsPerPageOptions` monta un `ITSelect` y el resumen «X - Y de Z», que solo aparece si se pasa `totalItems`.",
+          'Se envuelve en `<nav aria-label>`; anterior/siguiente usan `role="button"` con `aria-disabled` en los extremos.',
+        ],
+      }}
     />
   );
 };
@@ -197,6 +272,25 @@ export const TripleFilterShowcase = () => {
           <p className="text-slate-500">{t("showcase.nav.tripleFilterHint")}</p>
         </div>
       }
+      doc={{
+        summary:
+          "Filtro segmentado genérico estilo pill: solo una opción está activa y admite valores `string` o `boolean`.",
+        examples: [
+          '<ITTripleFilter value={filter} onChange={setFilter} options={[{ label: "Todos", value: "all" }, { label: "Activos", value: "active" }]} />',
+          '<ITTripleFilter value={onlyActive} onChange={setOnlyActive} options={[{ label: "Sí", value: true }, { label: "No", value: false }]} color="success" />',
+        ],
+        props: [
+          { name: "value", type: "T", required: true, description: "Valor seleccionado; debe coincidir con uno de `options[].value`." },
+          { name: "onChange", type: "(value: T) => void", required: true, description: "Se dispara al elegir otra opción, con el nuevo valor." },
+          { name: "options", type: "ITTripleFilterOption<T>[]", required: true, description: "Opciones a renderizar: { label, value }." },
+          { name: "color", type: "ColorsTypes", default: '"primary"', description: "Color del botón activo (primary, secondary, success, danger, warning, info, purple, error, gray)." },
+          { name: "className", type: "string", description: "Clases adicionales del contenedor." },
+        ],
+        notes: [
+          "Genérico sobre `T extends string | boolean`, así que el mismo componente sirve para estados y para banderas true/false.",
+          "Los botones no exponen `aria-pressed` ni `role`, por lo que el estado activo no se anuncia a lectores de pantalla.",
+        ],
+      }}
     />
   );
 };

package/src/showcases/PageShowcases.tsx

@@ -389,6 +389,30 @@ export const PageHeaderShowcase = () => {
           </div>
         </ITStack>
       }
+      doc={{
+        summary: "Barra de título de página con breadcrumbs, descripción, botón de volver y acciones.",
+        description:
+          "Es la cabecera que ITPage delega por defecto. Cuando hay breadcrumbs o backAction dibuja una fila superior con el botón de volver y las migas a la izquierda, y mueve `actions` a esa fila; sin fila superior las acciones quedan en la fila del título.",
+        examples: [
+          '<ITPageHeader title="Team members" description="Manage invitations, roles and permissions" />',
+          '<ITPageHeader\n  title="Usuarios"\n  icon={<FaUsers size={20} />}\n  iconColor="#6366f1"\n  breadcrumbs={[{ label: "Admin", href: "#" }, { label: "Usuarios" }]}\n  backAction={() => history.back()}\n  actions={<ITButton label="Invitar" size="sm" />}\n/>',
+          '<ITPageHeader title="Reportes" actions={<ITButton label="Exportar" variant="outlined" size="sm" />} />',
+        ],
+        props: [
+          { name: "title", type: "string", required: true, description: "Título principal, renderizado como <h1>." },
+          { name: "description", type: "string", description: "Texto descriptivo bajo el título." },
+          { name: "breadcrumbs", type: "ITBreadcrumbItem[]", description: "Migas de pan ({ label, href?, onClick? }); el último ítem se pinta como texto plano." },
+          { name: "actions", type: "ReactNode", description: "Botones o elementos alineados a la derecha." },
+          { name: "backAction", type: "() => void", description: "Se dispara al pulsar el botón de volver; su presencia basta para mostrar la fila superior." },
+          { name: "icon", type: "ReactNode", description: "Icono mostrado dentro del recuadro redondo junto al título." },
+          { name: "iconColor", type: "string", description: "Color CSS aplicado al recuadro del icono (style.color)." },
+          { name: "className", type: "string", description: "Clases adicionales del contenedor." },
+        ],
+        notes: [
+          "El recuadro del icono (w-12 h-12 redondo) no se renderiza en aspecto flat (`useITFlatAppearance()`); con ese aspecto el título se reduce y `iconColor` deja de tener efecto.",
+          "El botón de volver es un círculo de 9×9 con aria-label \"Volver\" (i18n `pageHeader.back`).",
+        ],
+      }}
     />
   );
 };
@@ -957,6 +981,44 @@ export const PageShowcase = () => {
           </div>
         </ITStack>
       }
+      doc={{
+        summary: "Plantilla de página: ancho máximo, cabecera opcional (ITPageHeader) y estados integrados de carga, error y vacío.",
+        description:
+          "Envuelve el contenido con el ancho y el padding de página y, si hay algo que mostrar, delega la cabecera en ITPageHeader. Los tres estados sustituyen a los children y también conservan la cabecera.",
+        examples: [
+          '<ITPage title="Team members" description="Manage your organization workspace" actions={<ITButton label="Invite" size="sm" />}>\n  <ITTable columns={columns} data={users} />\n</ITPage>',
+          '<ITPage title="Reportes" loading={loading} error={error} errorTitle="Error de carga" onRetry={refetch} maxWidth="6xl">\n  <ReportBody />\n</ITPage>',
+          '<ITPage title="Tablero" horizontalPadding="px-0">\n  <div>Contenido a sangre</div>\n</ITPage>',
+        ],
+        props: [
+          { name: "title", type: "string", description: "Título de la página, se pasa a la cabecera." },
+          { name: "description", type: "string", description: "Descripción bajo el título." },
+          { name: "breadcrumbs", type: "ITBreadcrumbItem[]", description: "Migas de pan para dar contexto de navegación." },
+          { name: "actions", type: "ReactNode", description: "Botones de acción de la cabecera." },
+          { name: "backAction", type: "() => void", description: "Callback del botón de volver." },
+          { name: "icon", type: "ReactNode", description: "Icono opcional junto al título." },
+          { name: "iconColor", type: "string", description: "Color CSS del icono." },
+          { name: "loading", type: "boolean", default: "false", description: "Muestra placeholders de esqueleto (tres skeletons rectangulares)." },
+          { name: "error", type: "string | null", default: "null", description: "Mensaje del estado de error; dibuja un ITEmptyState con botón de reintento si hay onRetry." },
+          { name: "errorTitle", type: "string", default: 'i18n common.error ("Error")', description: "Título del estado de error." },
+          { name: "errorActionLabel", type: "string", default: 'i18n common.retry ("Reintentar")', description: "Etiqueta del botón de reintento." },
+          { name: "onRetry", type: "() => void", description: "Callback del botón de reintento; solo se pinta si hay error." },
+          { name: "empty", type: "boolean", default: "false", description: "Muestra el estado vacío." },
+          { name: "emptyTitle", type: "string", default: 'i18n common.noData ("Sin datos")', description: "Título del estado vacío." },
+          { name: "emptyDescription", type: "string", default: 'i18n common.empty ("No hay información para mostrar")', description: "Descripción del estado vacío." },
+          { name: "emptyAction", type: "ReactNode", description: "Acción personalizada del estado vacío." },
+          { name: "children", type: "ReactNode", required: true, description: "Contenido renderizado dentro del wrapper." },
+          { name: "maxWidth", type: '"2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl"', default: '"7xl"', description: "Ancho máximo del contenido." },
+          { name: "noPadding", type: "boolean", default: "false", description: "Quita el padding por defecto y gana sobre horizontalPadding (también omite el py-6)." },
+          { name: "horizontalPadding", type: "string", default: '"px-4 sm:px-6 lg:px-8"', description: "Clases Tailwind del gutter horizontal; debe ser un literal que Tailwind pueda escanear." },
+          { name: "className", type: "string", description: "Clases adicionales del wrapper." },
+        ],
+        notes: [
+          "Prioridad de estados: loading > error > empty; si ninguno aplica se renderizan los children. La cabecera se incluye en los cuatro casos si hay título, descripción, breadcrumbs, acciones, backAction o icono.",
+          "Con noPadding se omiten a la vez el gutter horizontal y el py-6; horizontalPadding montado en runtime no llega al CSS generado por Tailwind, así que pásalo siempre literal.",
+          "maxWidth se compone como `max-w-${maxWidth}` en runtime; los literales max-w-2xl…max-w-7xl están en el código fuente y Tailwind los genera.",
+        ],
+      }}
     />
   );
 };

package/src/showcases/StructureShowcases.tsx

@@ -534,6 +534,33 @@ export const CardShowcase = () => {
           </GallerySection>
         </ITStack>
       }
+      doc={{
+        summary: "Contenedor de tarjeta con imagen, título, cuerpo y pie de acciones opcionales; con onClick se vuelve interactivo.",
+        description: "Pieza base de composición para agrupar contenido relacionado. Borde, radio y sombra se adaptan al aspecto del tema (flat / soft).",
+        examples: [
+          '<ITCard title="Ingresos del mes" actions={<ITButton label="Ver detalle" size="sm" />}>$48.230</ITCard>',
+          '<ITCard title="Curso" image="/courses/ts.jpg" imageClassName="h-32" onClick={() => open(course.id)}>…</ITCard>',
+          '<ITCard className="max-w-sm"><ITText muted>Tarjeta estática, sin cabecera ni acciones.</ITText></ITCard>',
+        ],
+        props: [
+          { name: "onClick", type: "() => void", default: "—", description: "Al recibirlo la tarjeta se vuelve clicable: cursor pointer, transición de sombra y elevación en hover. Sin él es estática." },
+          { name: "title", type: "string", default: "—", description: "Título de la cabecera; se renderiza como h3 mediante ITText." },
+          { name: "image", type: "string", default: "—", description: "URL de la imagen superior, a ancho completo con h-48 object-cover." },
+          { name: "alt", type: "string", default: "t(\"card.imageAlt\")", description: "Texto alternativo de la imagen; si se omite usa la key i18n card.imageAlt." },
+          { name: "children", type: "ReactNode", default: "—", description: "Contenido del cuerpo, debajo del título." },
+          { name: "actions", type: "ReactNode", default: "—", description: "Pie de acciones separado por un borde superior y anclado al fondo con mt-auto." },
+          { name: "className", type: "string", default: "—", description: "Clases del contenedor de la tarjeta." },
+          { name: "imageClassName", type: "string", default: "—", description: "Clases de la imagen; permite sobreescribir el h-48 por defecto." },
+          { name: "titleClassName", type: "string", default: "—", description: "Clases del título de la cabecera." },
+          { name: "contentClassName", type: "string", default: "—", description: "Clases del contenedor del cuerpo." },
+          { name: "actionClassName", type: "string", default: "—", description: "Clases del pie de acciones." },
+        ],
+        notes: [
+          "El aspecto del tema decide borde y sombra: en flat el borde es un hairline y solo hay sombra en hover si la tarjeta es clicable; en soft flota con --shadow-sm y sube a --shadow-lg con translateY(-2px).",
+          "Variables CSS: --it-card-bg, --it-card-border, --it-card-flat-border y --it-card-radius.",
+          "El padding es fijo (cuerpo 1.25rem, pie 1rem): no hay prop de tamaño.",
+        ],
+      }}
     />
   );
 };
@@ -910,6 +937,27 @@ export const TextShowcase = () => {
           </GallerySection>
         </ITStack>
       }
+      doc={{
+        summary: "Wrapper tipográfico semántico que renderiza cualquier elemento HTML (p, span, h1, label…) y reenvía los atributos estándar.",
+        description: "Aporta la capa de texto del sistema con el token muted; no impone clases tipográficas, así que tamaño, peso y color los define el className del consumidor.",
+        examples: [
+          '<ITText as="h1" className="text-2xl font-bold">Bienvenido</ITText>',
+          '<ITText as="p" muted className="text-sm">Descripción secundaria del panel.</ITText>',
+          '<ITText as="label" htmlFor="email">Correo electrónico</ITText>',
+        ],
+        props: [
+          { name: "children", type: "ReactNode", default: "—", description: "Contenido renderizado dentro del elemento." },
+          { name: "as", type: "ElementType", default: '"p"', description: "Elemento HTML a renderizar: p, span, h1, h2, label, code, etc." },
+          { name: "muted", type: "boolean", default: "false", description: "Aplica el color de texto atenuado (--color-text-muted) mediante style inline." },
+          { name: "htmlFor", type: "string", default: "—", description: "Asocia el texto con un campo de formulario; se reenvía como htmlFor cuando as es label." },
+          { name: "className", type: "string", default: "—", description: "Clases del elemento: definen tamaño, peso y color, porque el componente no añade ninguna." },
+        ],
+        notes: [
+          "Extiende HTMLAttributes<HTMLElement>, así que id, style, title, onClick, role y aria-* se reenvían al elemento renderizado.",
+          "muted se combina con el style propio: si el consumidor define color, gana el del consumidor.",
+          "Lo usan internamente otros componentes (avatar, button, badget, chip, checkbox, loader, radio, segmented-control, slider, textarea, tooltip) para etiquetas y textos.",
+        ],
+      }}
     />
   );
 };