@axzydev/axzy_ui_system 1.5.0 → 1.5.2

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

@@ -219,7 +219,7 @@ export const PageHeaderShowcase = () => {
         <ITStack spacing={6}>
           {/* 1. Team management — full header + search + filter bar + user rows */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryTeamManagement")}</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.pages.galleryTeamManagement")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 bg-white dark:border-slate-800 dark:bg-slate-950">
               <div className="p-5 pb-3">
                 <ITPageHeader
@@ -282,7 +282,7 @@ export const PageHeaderShowcase = () => {
 
           {/* 2. Detail page — back + breadcrumbs + back button + save/cancel */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryDetailEdit")}</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.pages.galleryDetailEdit")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 bg-white dark:border-slate-800 dark:bg-slate-950">
               <div className="p-5 pb-3">
                 <ITPageHeader
@@ -319,7 +319,7 @@ export const PageHeaderShowcase = () => {
 
           {/* 3. Dashboard header — icon + title + desc + date range + refresh */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryDashboard")}</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.pages.galleryDashboard")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 bg-white dark:border-slate-800 dark:bg-slate-950">
               <div className="p-5">
                 <ITPageHeader
@@ -345,7 +345,7 @@ export const PageHeaderShowcase = () => {
 
           {/* 4. Settings header — no icon, no breadcrumbs, just title + desc + save */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.gallerySettingsPrefs")}</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.pages.gallerySettingsPrefs")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 bg-white dark:border-slate-800 dark:bg-slate-950">
               <div className="p-5">
                 <ITPageHeader
@@ -364,7 +364,7 @@ export const PageHeaderShowcase = () => {
 
           {/* 5. Users list — icon + breadcrumbs + search in actions + add button */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryUsersList")}</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.pages.galleryUsersList")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 bg-white dark:border-slate-800 dark:bg-slate-950">
               <div className="p-5">
                 <ITPageHeader
@@ -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`).",
+        ],
+      }}
     />
   );
 };
@@ -712,7 +736,7 @@ export const PageShowcase = () => {
         <ITStack spacing={6}>
           {/* 1. Users list with ITTable */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryUsersTable")}</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.pages.galleryUsersTable")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITPage
                 horizontalPadding={hPaddingValue}
@@ -740,7 +764,7 @@ export const PageShowcase = () => {
 
           {/* 2. Product detail */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryProductDetail")}</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.pages.galleryProductDetail")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITPage
                 horizontalPadding={hPaddingValue}
@@ -788,7 +812,7 @@ export const PageShowcase = () => {
 
           {/* 3. Edit profile form */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryEditProfile")}</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.pages.galleryEditProfile")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITPage
                 horizontalPadding={hPaddingValue}
@@ -839,7 +863,7 @@ export const PageShowcase = () => {
 
           {/* 4. Orders with table */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.galleryOrdersTable")}</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.pages.galleryOrdersTable")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITPage
                 horizontalPadding={hPaddingValue}
@@ -892,7 +916,7 @@ export const PageShowcase = () => {
 
           {/* 5. Settings with tabs */}
           <div>
-            <h3 className="mb-3 font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">{t("showcase.pages.gallerySettings")}</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.pages.gallerySettings")}</h3>
             <div className="overflow-hidden rounded-[10px] border border-slate-200 dark:border-slate-800">
               <ITPage
                 horizontalPadding={hPaddingValue}
@@ -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.",
+        ],
+      }}
     />
   );
 };