siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/NavigationBar/NavigationBar.stories.tsx

@@ -0,0 +1,406 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { NavigationBar } from './NavigationBar';
+import type { NavigationBarItem } from './NavigationBar.types';
+
+// ===== ICONOS DE EJEMPLO =====
+// Iconos simples de heroicons-micro (16x16px)
+const HomeIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M6.5 14.5v-3.505c0-.245.25-.495.5-.495h2c.25 0 .5.25.5.495V14.5m-7-3c0-2.485 0-3.729.586-4.664.586-.936 1.586-1.479 3.586-2.564l.328-.179C7.712 3.348 8.26 3 8.76 3c.5 0 1.048.348 2.26 1.093l.328.179c2 1.085 3 1.628 3.586 2.564.586.935.586 2.179.586 4.664v1c0 2.8 0 4.2-.545 5.27a5 5 0 0 1-2.185 2.185C11.7 20.5 10.3 20.5 7.5 20.5h1c-2.8 0-4.2 0-5.27-.545a5 5 0 0 1-2.185-2.185C.5 16.7.5 15.3.5 12.5v-1Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const SearchIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M14 14l-2.9-2.9M12.667 7.333A5.333 5.333 0 1 1 2 7.333a5.333 5.333 0 0 1 10.667 0Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const HeartIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M13.732 3.268A4 4 0 0 0 8.4 2.4L8 2.8l-.4-.4a4 4 0 0 0-5.332.932 4 4 0 0 0 .532 5.732l5.2 5.2 5.2-5.2a4 4 0 0 0 .532-5.796Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const BellIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M6 13.333a2 2 0 1 0 4 0M11.333 5.333a3.333 3.333 0 1 0-6.666 0c0 3.773-1.334 5.334-1.334 5.334h9.334s-1.334-1.56-1.334-5.334Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const UserIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M13.333 14v-1.333A2.667 2.667 0 0 0 10.667 10H5.333a2.667 2.667 0 0 0-2.666 2.667V14M8 7.333A2.667 2.667 0 1 0 8 2a2.667 2.667 0 0 0 0 5.333Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const meta = {
+  title: 'Siesa UI Kit/NavigationBar',
+  component: NavigationBar,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Barra de navegación inferior (Bottom Navigation Bar) para aplicaciones móviles. Permite al usuario navegar entre 3-5 vistas principales de la aplicación.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    items: {
+      control: 'object',
+      description: 'Lista de ítems del navigation bar (máximo 5 recomendado)',
+      table: {
+        type: { summary: 'NavigationBarItem[]' },
+        category: 'Contenido',
+      },
+    },
+    activeItemId: {
+      control: 'text',
+      description: 'ID del ítem actualmente activo',
+      table: {
+        type: { summary: 'string' },
+        category: 'Estado',
+      },
+    },
+    onItemClick: {
+      action: 'itemClicked',
+      description: 'Función que se ejecuta cuando se hace click en un ítem',
+      table: {
+        type: { summary: '(id: string) => void' },
+        category: 'Comportamiento',
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Clases CSS adicionales',
+      table: {
+        type: { summary: 'string' },
+        category: 'Apariencia',
+      },
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Etiqueta accesible para el navigation bar',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accesibilidad',
+      },
+    },
+  },
+} satisfies Meta<typeof NavigationBar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ===== DATOS DE EJEMPLO =====
+const sampleItems: NavigationBarItem[] = [
+  { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+  { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+  { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+];
+
+// ============================================
+// 1. PLAYGROUND INTERACTIVO
+// ============================================
+export const Playground: Story = {
+  args: {
+    items: sampleItems,
+    activeItemId: 'home',
+    ariaLabel: 'Navegación Principal',
+  },
+  render: (args) => {
+    const [activeId, setActiveId] = useState(args.activeItemId || 'home');
+
+    return (
+      <div className="w-full flex items-end bg-background-secondary dark:bg-dark-bg-primary">
+        <NavigationBar
+          {...args}
+          activeItemId={activeId}
+          onItemClick={(id) => {
+            setActiveId(id);
+            args.onItemClick?.(id);
+          }}
+        />
+      </div>
+    );
+  },
+};
+
+// ============================================
+// 2. VARIANTES DE CANTIDAD DE ÍTEMS
+// ============================================
+export const VariantesDeItems: Story = {
+  args: {
+    items: [],
+  },
+  render: () => (
+    <div className="space-y-8 p-6 bg-background-secondary dark:bg-dark-bg-primary">
+      {/* 3 Items */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          3 Ítems (Mínimo Recomendado)
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="home"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Ideal para aplicaciones simples con pocas secciones principales
+        </p>
+      </div>
+
+      {/* 4 Items */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          4 Ítems (Óptimo)
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="home"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Balance perfecto entre funcionalidad y usabilidad
+        </p>
+      </div>
+
+      {/* 5 Items */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          5 Ítems (Máximo Recomendado)
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar items={sampleItems} activeItemId="home" />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Máximo de ítems para mantener buena experiencia de usuario
+        </p>
+      </div>
+
+      {/* Tips */}
+      <div className="mt-6 p-4 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
+        <p className="text-xs text-content-primary dark:text-dark-content-primary">
+          <strong>💡 Consejos:</strong>
+          <br />• Usa entre 3 y 5 ítems para mejor usabilidad
+          <br />• El primer ítem suele ser "Inicio" o la vista principal
+          <br />• Evita labels muy largos (máximo 10 caracteres)
+          <br />• Los iconos deben ser simples y reconocibles
+        </p>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 3. ESTADOS
+// ============================================
+export const Estados: Story = {
+  args: {
+    items: [],
+  },
+  render: () => (
+    <div className="space-y-8 p-6 bg-background-secondary dark:bg-dark-bg-primary">
+      {/* Estado Normal - Primer ítem activo */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Estado Normal (Primer Ítem Activo)
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="home"
+          />
+        </div>
+      </div>
+
+      {/* Estado con ítem central activo */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Ítem Central Activo
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos', active: true },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="favorites"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          El ítem activo tiene fondo azul claro (light mode) o azul oscuro transparente (dark
+          mode)
+        </p>
+      </div>
+
+      {/* Estado con ítem deshabilitado */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Con Ítem Deshabilitado
+        </h3>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              {
+                id: 'favorites',
+                icon: <HeartIcon />,
+                label: 'Favoritos',
+                disabled: true,
+              },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="home"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Los ítems deshabilitados tienen opacidad reducida y no responden a clicks
+        </p>
+      </div>
+
+      {/* Estado hover */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Estado Hover
+        </h3>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mb-2">
+          Pasa el mouse sobre los ítems inactivos para ver el efecto de hover
+        </p>
+        <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+          <NavigationBar
+            items={[
+              { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+              { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+              { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+              { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+            ]}
+            activeItemId="home"
+          />
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 4. EJEMPLOS DE USO
+// ============================================
+export const EjemplosDeUso: Story = {
+  args: {
+    items: [],
+  },
+  render: () => {
+    const [activeTab1, setActiveTab1] = useState('home');
+    const [activeTab2, setActiveTab2] = useState('home');
+
+    return (
+      <div className="space-y-8 p-6 bg-background-secondary dark:bg-dark-bg-primary">
+        {/* Ejemplo 1: E-commerce */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+            App de E-commerce
+          </h3>
+          <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+            <NavigationBar
+              items={[
+                { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+                { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+                { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+                { id: 'profile', icon: <UserIcon />, label: 'Cuenta' },
+              ]}
+              activeItemId={activeTab1}
+              onItemClick={setActiveTab1}
+            />
+          </div>
+        </div>
+
+        {/* Ejemplo 2: Red Social */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+            Red Social
+          </h3>
+          <div className="bg-bg-primary dark:bg-dark-bg-primary rounded-2xl overflow-hidden">
+            <NavigationBar
+              items={[
+                { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+                { id: 'search', icon: <SearchIcon />, label: 'Explorar' },
+                { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+                { id: 'favorites', icon: <HeartIcon />, label: 'Guardados' },
+                { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+              ]}
+              activeItemId={activeTab2}
+              onItemClick={setActiveTab2}
+            />
+          </div>
+        </div>
+
+        {/* Tips */}
+        <div className="mt-6 p-4 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
+          <p className="text-xs text-content-primary dark:text-dark-content-primary">
+            <strong>💡 Cuándo usar NavigationBar:</strong>
+            <br />• Aplicaciones móviles con 3-5 secciones principales
+            <br />• Navegación persistente entre vistas de igual jerarquía
+            <br />• Apps donde el usuario necesita cambiar frecuentemente entre secciones
+            <br />• NO usar en web desktop (considera tabs o sidebar en su lugar)
+          </p>
+        </div>
+      </div>
+    );
+  },
+};
+

package/src/components/NavigationBar/NavigationBar.tsx

@@ -0,0 +1,246 @@
+import React from 'react';
+import type { NavigationBarProps, NavigationBarItem } from './NavigationBar.types';
+
+/**
+ * NavigationBar del sistema de diseño Siesa
+ *
+ * **Componente de navegación inferior (Bottom Navigation Bar) para móvil.**
+ * Permite al usuario navegar entre vistas principales de la aplicación.
+ * Diseñado para contener 3-5 ítems de navegación.
+ *
+ * **🔄 Navegación Responsive:**
+ * El NavigationRail (navegación lateral vertical) se convierte en NavigationBar
+ * (navegación inferior horizontal) cuando la pantalla es móvil. Esta es una
+ * práctica recomendada de UX para aprovechar mejor el espacio en diferentes
+ * dispositivos:
+ * - **Desktop/Tablet**: Usar NavigationRail (lateral)
+ * - **Mobile**: Usar NavigationBar (inferior)
+ *
+ * **Características:**
+ * - Soporta hasta 5 ítems de navegación (recomendado: 3-5)
+ * - Cada ítem tiene icono + label
+ * - Indicador visual de ítem activo (fondo azul claro)
+ * - Estados: active, hover, disabled
+ * - Dark mode completo
+ * - Accesibilidad con ARIA labels
+ *
+ * **Mejores prácticas implementadas:**
+ * - Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+ * - Dark mode con estrategia 'class' (darkMode: 'class')
+ * - Tokens de color consistentes con la documentación
+ * - Type safety con TypeScript estricto
+ * - Tipografía Label XXSmall (10px Bold) según sistema de diseño
+ * - Iconos de 16x16px según especificaciones de Figma
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label XXSmall)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see NavigationRail - Componente de navegación lateral para desktop
+ *
+ * @example
+ * ```tsx
+ * const items = [
+ *   { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+ *   { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+ *   { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+ * ];
+ *
+ * <NavigationBar
+ *   items={items}
+ *   activeItemId="home"
+ *   onItemClick={(id) => console.log('Clicked:', id)}
+ * />
+ * ```
+ *
+ * @example
+ * // Patrón responsive: NavigationRail en desktop, NavigationBar en mobile
+ * ```tsx
+ * function ResponsiveNav() {
+ *   return (
+ *     <>
+ *       // NavigationRail para desktop/tablet
+ *       <div className="hidden md:block">
+ *         <NavigationRail items={items} />
+ *       </div>
+ *
+ *       // NavigationBar para móvil
+ *       <div className="md:hidden fixed bottom-0 left-0 right-0 z-50">
+ *         <NavigationBar items={items} />
+ *       </div>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export const NavigationBar: React.FC<NavigationBarProps> = ({
+  items,
+  activeItemId,
+  onItemClick,
+  className = '',
+  ariaLabel = 'Navegación Principal',
+}) => {
+  // ===== VALIDACIÓN: Máximo 5 ítems =====
+  if (items.length > 5) {
+    console.warn('NavigationBar: Se recomienda un máximo de 5 ítems para mejor UX');
+  }
+
+  // ===== HANDLER DE CLICK =====
+  const handleItemClick = (item: NavigationBarItem) => {
+    if (item.disabled) return;
+
+    // Llamar onClick del ítem individual si existe
+    if (item.onClick) {
+      item.onClick(item.id);
+    }
+
+    // Llamar onItemClick global si existe
+    if (onItemClick) {
+      onItemClick(item.id);
+    }
+  };
+
+  // ===== RENDERIZAR ÍTEM =====
+  const renderItem = (item: NavigationBarItem) => {
+    const isActive = item.active || item.id === activeItemId;
+
+    // ===== CLASES DEL CONTENEDOR DEL ÍTEM =====
+    const itemContainerClasses = `
+      flex-1
+      flex
+      flex-col
+      items-center
+      gap-1
+      px-0.5
+      py-0
+      min-w-0
+      cursor-pointer
+      transition-all
+      duration-150
+      ${item.disabled ? 'opacity-50 cursor-not-allowed pointer-events-none' : ''}
+    `
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    // ===== CLASES DEL ICON CONTAINER =====
+    // Fondo azul claro cuando está activo (rgb(219, 238, 254) = #dbeefe = primary-custom-100)
+    // En dark mode usa el mismo color opaco según Figma
+    const iconContainerClasses = `
+      flex
+      items-center
+      justify-center
+      px-4
+      py-1
+      rounded-full
+      overflow-hidden
+      transition-all
+      duration-150
+      ${
+        isActive
+          ? 'bg-primary-custom-100 dark:bg-primary-custom-100'
+          : 'bg-transparent hover:bg-hover-overlay dark:hover:bg-hover-overlay-dark'
+      }
+    `
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    // ===== CLASES DEL LABEL =====
+    // Label XXSmall: 10px Bold, line-height 12px (según typography.md y Figma)
+    const labelClasses = `
+      font-['SiesaBT:Bold',sans-serif]
+      text-[10px]
+      leading-[12px]
+      font-bold
+      text-center
+      w-full
+      min-w-0
+      text-content-primary
+      dark:text-dark-content-primary
+      transition-colors
+      duration-150
+    `
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    // ===== CLASES DEL ICONO =====
+    // Iconos de 16x16px según Figma
+    const iconClasses = `
+      w-4
+      h-4
+      shrink-0
+      text-content-primary
+      dark:text-dark-content-primary
+      transition-colors
+      duration-150
+    `
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    return (
+      <button
+        key={item.id}
+        type="button"
+        className={itemContainerClasses}
+        onClick={() => handleItemClick(item)}
+        disabled={item.disabled}
+        aria-label={item.ariaLabel || item.label}
+        aria-current={isActive ? 'page' : undefined}
+      >
+        {/* Icon Container */}
+        <div className={iconContainerClasses}>
+          <span className={iconClasses}>{item.icon}</span>
+        </div>
+
+        {/* Label */}
+        <span className={labelClasses}>{item.label}</span>
+      </button>
+    );
+  };
+
+  // ===== CLASES DEL CONTENEDOR PRINCIPAL =====
+  const containerClasses = `
+    bg-bg-primary
+    dark:bg-dark-bg-primary
+    p-4
+    w-full
+    transition-colors
+    duration-150
+  `
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES DEL MENU (Contenedor de ítems) =====
+  const menuClasses = `
+    flex
+    items-start
+    justify-center
+    w-full
+  `
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES DEL DESTINATIONS (Contenedor con gap) =====
+  const destinationsClasses = `
+    flex-1
+    flex
+    items-start
+    gap-2
+    min-h-0
+    min-w-0
+  `
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return (
+    <nav
+      className={`${containerClasses} ${className}`.trim()}
+      role="navigation"
+      aria-label={ariaLabel}
+    >
+      <div className={menuClasses}>
+        <div className={destinationsClasses}>
+          {items.map((item) => renderItem(item))}
+        </div>
+      </div>
+    </nav>
+  );
+};