@axzydev/axzy_ui_system 1.5.1 → 1.5.3

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.",
+        ],
+      }}
     />
   );
 };

package/src/types/button.types.ts

@@ -5,7 +5,8 @@ export const buttonVariants: Record<string, string> = {
   rounded: "border-transparent shadow-sm rounded-full",
   text: "bg-transparent border-transparent shadow-none hover:bg-black/5 dark:hover:bg-white/10",
   "raised-text": "bg-white border border-gray-200 shadow-sm hover:shadow-md",
-  "icon-only": "p-2 aspect-square flex items-center justify-center border-transparent shadow-sm",
+  // No lleva utilidades de padding: el cuadrado lo define `buttonIconPadding` por tamaño.
+  "icon-only": "aspect-square flex items-center justify-center border-transparent shadow-sm",
   link: "bg-transparent border-transparent shadow-none hover:underline px-0",
 };
 
@@ -14,3 +15,20 @@ export const buttonSizes: Record<string, string> = {
   md: "text-[13px] px-3.5 py-1.5",
   lg: "text-sm px-4 py-2",
 };
+
+/**
+ * Tipografía de `icon-only`: solo el tamaño de fuente, sin padding horizontal/vertical,
+ * para que el padding simétrico de `buttonIconPadding` no compita con `buttonSizes`.
+ */
+export const buttonIconSizes: Record<string, string> = {
+  sm: "text-xs",
+  md: "text-[13px]",
+  lg: "text-sm",
+};
+
+/** Padding simétrico (px) del botón `icon-only` por tamaño; define el cuadrado con `aspect-square`. */
+export const buttonIconPadding: Record<string, string> = {
+  sm: "0.5rem",
+  md: "0.625rem",
+  lg: "0.75rem",
+};