siesa-ui-kit 1.0.4 → 1.0.5

package/src/components/Navbar/README.md

@@ -1,279 +1,279 @@
-# Navbar
-
-Barra de navegación principal del sistema de diseño Siesa UI Kit con soporte completo para responsive design y dark mode.
-
-## Características
-
-- **4 Variantes**: `responsive` (default), `desktop`, `tablet`, `mobile`
-- **Dark Mode Completo**: Todos los elementos con tokens adaptativos
-- **Tokens del Sistema**: NO colores hardcodeados
-- **Focus Rings Adaptativos**: Para accesibilidad en light y dark mode
-- **Logo Personalizable**: Acepta componente custom o usa logo por defecto
-- **Badge de Ambiente**: Usa el componente Badge con color yellow del sistema
-- **Notificaciones**: Badges con token `error-content` para consistencia
-- **Dropdown de Usuario**: Avatar con nombre y email
-- **Logo Siesa Trailing**: Opcional, solo en desktop
-- **TypeScript Estricto**: Tipado completo con interfaces
-- **Accesibilidad**: ARIA labels en todos los botones
-- **Handlers de Eventos**: Callbacks para navegación, búsqueda, carrito y notificaciones
-
-## Especificaciones de Figma
-
-| Variante | Tamaño | Elementos |
-|----------|--------|-----------|
-| **Desktop** | 1360x64px | Botón nav, Logo business, Siesa logo, Nombre producto, Badge, Botones, Dropdown, Siesa logo trailing |
-| **Tablet** | 1024x64px | Similar a desktop pero logos más pequeños, sin Siesa trailing |
-| **Mobile** | 428x40px | Solo Siesa icono (30x30), Badge "Pruebas", Botón búsqueda, Avatar circular |
-
-## Instalación
-
-```tsx
-import { Navbar } from '@/components/Navbar';
-```
-
-## Uso Básico
-
-```tsx
-<Navbar
-  productName="Mi Aplicación"
-  environmentBadge="Ambiente de Pruebas"
-  userDropdown={{
-    avatar: "/path/to/avatar.jpg",
-    name: "Juan Pérez",
-    email: "juan@ejemplo.com",
-  }}
-/>
-```
-
-## Con Handlers de Eventos
-
-```tsx
-<Navbar
-  productName="Portal Empresarial"
-  environmentBadge="Ambiente de Pruebas"
-  userDropdown={{
-    avatar: "/path/to/avatar.jpg",
-    name: "María García",
-    email: "maria@miempresa.com",
-    onMenuClick: () => openUserMenu(),
-  }}
-  notifications={{
-    cart: 15,
-    bell: true,
-  }}
-  onNavigationClick={() => router.back()}
-  onSearchClick={() => openSearch()}
-  onCartClick={() => openCart()}
-  onNotificationsClick={() => openNotifications()}
-/>
-```
-
-## Variantes de Dispositivo
-
-### Desktop
-
-```tsx
-<Navbar
-  variant="desktop"
-  productName="Sistema de Gestión"
-  showTrailingSiesaLogo={true}
-  // ... resto de props
-/>
-```
-
-### Tablet
-
-```tsx
-<Navbar
-  variant="tablet"
-  productName="Sistema de Gestión"
-  // ... resto de props
-/>
-```
-
-### Mobile
-
-```tsx
-<Navbar
-  variant="mobile"
-  environmentBadge="Ambiente de Pruebas"
-  // productName se ignora en mobile
-  // ... resto de props
-/>
-```
-
-## Props
-
-### NavbarProps
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `logo` | `ReactNode` | Logo business | Logo del negocio/cliente (solo desktop/tablet) |
-| `siesaLogo` | `ReactNode` | Logo Siesa | Logo de Siesa personalizado |
-| `productName` | `string` | `'Nombre Producto'` | Nombre del producto (solo desktop/tablet) |
-| `environmentBadge` | `string` | `undefined` | Texto del badge de ambiente |
-| `userDropdown` | `UserDropdownProps` | `undefined` | Datos del dropdown de usuario |
-| `actions` | `ReactNode` | `undefined` | Elementos adicionales en trailing |
-| `notifications` | `NotificationsProps` | `undefined` | Configuración de badges |
-| `className` | `string` | `''` | Clases CSS adicionales |
-| `variant` | `NavbarVariant` | `'responsive'` | Modo de visualización |
-| `hideActionButtons` | `boolean` | `false` | Ocultar botones de acción |
-| `leadingAction` | `ReactNode` | `undefined` | Elemento leading personalizado |
-| `showTrailingSiesaLogo` | `boolean` | `true` | Mostrar Siesa logo en trailing (solo desktop) |
-| `onNavigationClick` | `() => void` | `undefined` | Handler para botón de navegación |
-| `onSearchClick` | `() => void` | `undefined` | Handler para búsqueda (solo mobile) |
-| `onCartClick` | `() => void` | `undefined` | Handler para carrito |
-| `onNotificationsClick` | `() => void` | `undefined` | Handler para notificaciones |
-
-### UserDropdownProps
-
-```typescript
-interface UserDropdownProps {
-  avatar: string;         // URL del avatar (mínimo 80x80px para retina)
-  name: string;           // Nombre del usuario
-  email?: string;         // Email del usuario
-  role?: string;          // Rol (alternativa a email)
-  onMenuClick?: () => void; // Handler para click
-}
-```
-
-### NotificationsProps
-
-```typescript
-interface NotificationsProps {
-  cart?: number;    // Número de items (>99 muestra "+99")
-  bell?: boolean;   // Dot de notificación
-}
-```
-
-### NavbarVariant
-
-```typescript
-type NavbarVariant = 'responsive' | 'desktop' | 'tablet' | 'mobile';
-```
-
-## Dark Mode
-
-El componente se adapta automáticamente al dark mode usando la clase `.dark` en el elemento `<html>`.
-
-### Tokens de Color
-
-| Elemento | Light Token | Dark Token |
-|----------|-------------|------------|
-| **Fondo** | `bg-background-primary` | `dark:bg-dark-bg-primary` |
-| **Texto principal** | `text-content-primary` | `dark:text-dark-content-primary` |
-| **Texto secundario** | `text-content-secondary` | `dark:text-content-secondary` |
-| **Bordes divider** | `bg-border-primary` | `dark:bg-dark-border-primary` |
-| **Iconos acción** | `text-primary-custom-600` | `dark:text-primary-custom-600` |
-| **Hover buttons** | `hover:bg-background-secondary` | `dark:hover:bg-dark-bg-secondary` |
-| **Botón navegación** | `bg-primary-custom-600` | `dark:bg-dark-bg-inverse` |
-| **Badge notificación** | `bg-error-content` | `dark:bg-error-content` |
-| **Focus ring** | `focus:ring-primary-custom-400` | `dark:focus:ring-dark-border-custom` |
-| **Focus offset** | `focus:ring-offset-2` | `dark:focus:ring-offset-dark-bg-primary` |
-
-### Estados Interactivos
-
-Todos los botones incluyen:
-- **Hover**: Cambio de fondo adaptativo
-- **Active**: `scale-95` para feedback visual
-- **Focus**: Ring adaptativo con offset correcto
-- **Transiciones**: `transition-all duration-150`
-
-## Responsive Behavior
-
-| Elemento | Desktop (lg:) | Tablet (md:) | Mobile |
-|----------|---------------|--------------|--------|
-| **Altura** | 64px | 64px | 40px |
-| **Botón navegación** | Visible | Visible | Oculto |
-| **Business Logo** | 168x30px | 140x25px | Oculto |
-| **Siesa Logo Leading** | 120x30px | 100x25px | 30x30px (icono) |
-| **Nombre producto** | Visible | Visible | Oculto |
-| **Dividers** | Visibles | Visibles | Ocultos |
-| **Badge ambiente** | Texto completo | Texto completo | "Pruebas" |
-| **Botón búsqueda** | Oculto | Oculto | Visible |
-| **Avatar** | 40x40 rounded-md | 40x40 rounded-md | 32x32 rounded-full |
-| **Nombre/email** | Visibles | Visibles | Ocultos |
-| **Chevron** | Visible | Visible | Oculto |
-| **Siesa Logo Trailing** | Visible | Oculto | Oculto |
-
-## Mejores Prácticas
-
-### Hacer
-
-1. Usar la variante `responsive` (default) para adaptación automática
-2. Proporcionar siempre `userDropdown` para mostrar información del usuario
-3. Usar avatares de alta resolución (mínimo 80x80px)
-4. Mantener `productName` corto (idealmente <25 caracteres)
-5. Actualizar `notifications` dinámicamente
-6. Usar solo tokens del sistema para customización
-7. Testear estados de focus con teclado (Tab)
-8. Implementar handlers para interactividad
-
-### Evitar
-
-1. No forzar variantes a menos que sea necesario
-2. No usar textos muy largos en `productName`
-3. No olvidar `environmentBadge` en desarrollo/prueba
-4. No mezclar el navbar con otros headers
-5. No usar colores hardcodeados (hex)
-6. No omitir handlers para elementos interactivos
-
-## Archivos del Componente
-
-```
-src/components/Navbar/
-├── Navbar.tsx          # Componente principal
-├── Navbar.types.ts     # Tipos e interfaces
-├── Navbar.stories.tsx  # Stories de Storybook
-├── icons.tsx           # Iconos Heroicons Micro
-├── index.ts            # Exports
-└── README.md           # Documentación
-```
-
-## Referencias
-
-- **Figma**: [Navbar Component](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4278-18626&m=dev)
-- **Docs**:
-  - `docs/colors.md` - Sistema de colores
-  - `docs/typography.md` - Sistema tipográfico
-  - `docs/spacing.md` - Sistema de espaciado
-  - `docs/shadows.md` - Sistema de sombras
-  - `docs/dark-mode-guide.md` - Guía de dark mode
-
-## Changelog
-
-### Version 1.2.0 (2025-12-02) - Corrección Completa Siesa UI Kit Specialist
-
-**Nuevas características:**
-- Variante `tablet` añadida para soporte completo responsive
-- `showTrailingSiesaLogo` prop para controlar logo Siesa en trailing
-- Handlers de eventos: `onNavigationClick`, `onSearchClick`, `onCartClick`, `onNotificationsClick`
-- Tipos exportados: `NavbarVariant`, `UserDropdownProps`, `NotificationsProps`
-
-**Correcciones:**
-- Dark mode completo en todos los elementos con tokens del sistema
-- Focus rings adaptativos para light y dark mode
-- Botón de navegación con `shadow-button-inset` según Button de referencia
-- Badge de ambiente usa componente Badge correctamente
-- Hover states con tokens: `hover:bg-background-secondary` / `dark:hover:bg-dark-bg-secondary`
-- Fondo del navbar con tokens: `bg-background-primary` / `dark:bg-dark-bg-primary`
-
-**Mejoras:**
-- JSDoc completo con referencias `@see` a documentación
-- Stories actualizadas con ejemplos de todas las variantes
-- README actualizado con tabla de tokens y especificaciones
-
-### Version 1.1.0 (2025-11-19)
-- Corrección de colores hardcodeados
-- Añadidos focus rings adaptativos
-- Active states con scale-95
-
-### Version 1.0.0 (2025-11-18)
-- Componente inicial con soporte responsive
-- Dark mode básico
-- Badges de notificación
-
----
-
-**Mantenido por**: Equipo Siesa UI Kit
-**Última actualización**: 2025-12-02
+# Navbar
+
+Barra de navegación principal del sistema de diseño Siesa UI Kit con soporte completo para responsive design y dark mode.
+
+## Características
+
+- **4 Variantes**: `responsive` (default), `desktop`, `tablet`, `mobile`
+- **Dark Mode Completo**: Todos los elementos con tokens adaptativos
+- **Tokens del Sistema**: NO colores hardcodeados
+- **Focus Rings Adaptativos**: Para accesibilidad en light y dark mode
+- **Logo Personalizable**: Acepta componente custom o usa logo por defecto
+- **Badge de Ambiente**: Usa el componente Badge con color yellow del sistema
+- **Notificaciones**: Badges con token `error-content` para consistencia
+- **Dropdown de Usuario**: Avatar con nombre y email
+- **Logo Siesa Trailing**: Opcional, solo en desktop
+- **TypeScript Estricto**: Tipado completo con interfaces
+- **Accesibilidad**: ARIA labels en todos los botones
+- **Handlers de Eventos**: Callbacks para navegación, búsqueda, carrito y notificaciones
+
+## Especificaciones de Figma
+
+| Variante | Tamaño | Elementos |
+|----------|--------|-----------|
+| **Desktop** | 1360x64px | Botón nav, Logo business, Siesa logo, Nombre producto, Badge, Botones, Dropdown, Siesa logo trailing |
+| **Tablet** | 1024x64px | Similar a desktop pero logos más pequeños, sin Siesa trailing |
+| **Mobile** | 428x40px | Solo Siesa icono (30x30), Badge "Pruebas", Botón búsqueda, Avatar circular |
+
+## Instalación
+
+```tsx
+import { Navbar } from '@/components/Navbar';
+```
+
+## Uso Básico
+
+```tsx
+<Navbar
+  productName="Mi Aplicación"
+  environmentBadge="Ambiente de Pruebas"
+  userDropdown={{
+    avatar: "/path/to/avatar.jpg",
+    name: "Juan Pérez",
+    email: "juan@ejemplo.com",
+  }}
+/>
+```
+
+## Con Handlers de Eventos
+
+```tsx
+<Navbar
+  productName="Portal Empresarial"
+  environmentBadge="Ambiente de Pruebas"
+  userDropdown={{
+    avatar: "/path/to/avatar.jpg",
+    name: "María García",
+    email: "maria@miempresa.com",
+    onMenuClick: () => openUserMenu(),
+  }}
+  notifications={{
+    cart: 15,
+    bell: true,
+  }}
+  onNavigationClick={() => router.back()}
+  onSearchClick={() => openSearch()}
+  onCartClick={() => openCart()}
+  onNotificationsClick={() => openNotifications()}
+/>
+```
+
+## Variantes de Dispositivo
+
+### Desktop
+
+```tsx
+<Navbar
+  variant="desktop"
+  productName="Sistema de Gestión"
+  showTrailingSiesaLogo={true}
+  // ... resto de props
+/>
+```
+
+### Tablet
+
+```tsx
+<Navbar
+  variant="tablet"
+  productName="Sistema de Gestión"
+  // ... resto de props
+/>
+```
+
+### Mobile
+
+```tsx
+<Navbar
+  variant="mobile"
+  environmentBadge="Ambiente de Pruebas"
+  // productName se ignora en mobile
+  // ... resto de props
+/>
+```
+
+## Props
+
+### NavbarProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `logo` | `ReactNode` | Logo business | Logo del negocio/cliente (solo desktop/tablet) |
+| `siesaLogo` | `ReactNode` | Logo Siesa | Logo de Siesa personalizado |
+| `productName` | `string` | `'Nombre Producto'` | Nombre del producto (solo desktop/tablet) |
+| `environmentBadge` | `string` | `undefined` | Texto del badge de ambiente |
+| `userDropdown` | `UserDropdownProps` | `undefined` | Datos del dropdown de usuario |
+| `actions` | `ReactNode` | `undefined` | Elementos adicionales en trailing |
+| `notifications` | `NotificationsProps` | `undefined` | Configuración de badges |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `variant` | `NavbarVariant` | `'responsive'` | Modo de visualización |
+| `hideActionButtons` | `boolean` | `false` | Ocultar botones de acción |
+| `leadingAction` | `ReactNode` | `undefined` | Elemento leading personalizado |
+| `showTrailingSiesaLogo` | `boolean` | `true` | Mostrar Siesa logo en trailing (solo desktop) |
+| `onNavigationClick` | `() => void` | `undefined` | Handler para botón de navegación |
+| `onSearchClick` | `() => void` | `undefined` | Handler para búsqueda (solo mobile) |
+| `onCartClick` | `() => void` | `undefined` | Handler para carrito |
+| `onNotificationsClick` | `() => void` | `undefined` | Handler para notificaciones |
+
+### UserDropdownProps
+
+```typescript
+interface UserDropdownProps {
+  avatar: string;         // URL del avatar (mínimo 80x80px para retina)
+  name: string;           // Nombre del usuario
+  email?: string;         // Email del usuario
+  role?: string;          // Rol (alternativa a email)
+  onMenuClick?: () => void; // Handler para click
+}
+```
+
+### NotificationsProps
+
+```typescript
+interface NotificationsProps {
+  cart?: number;    // Número de items (>99 muestra "+99")
+  bell?: boolean;   // Dot de notificación
+}
+```
+
+### NavbarVariant
+
+```typescript
+type NavbarVariant = 'responsive' | 'desktop' | 'tablet' | 'mobile';
+```
+
+## Dark Mode
+
+El componente se adapta automáticamente al dark mode usando la clase `.dark` en el elemento `<html>`.
+
+### Tokens de Color
+
+| Elemento | Light Token | Dark Token |
+|----------|-------------|------------|
+| **Fondo** | `bg-background-primary` | `dark:bg-dark-bg-primary` |
+| **Texto principal** | `text-content-primary` | `dark:text-dark-content-primary` |
+| **Texto secundario** | `text-content-secondary` | `dark:text-content-secondary` |
+| **Bordes divider** | `bg-border-primary` | `dark:bg-dark-border-primary` |
+| **Iconos acción** | `text-primary-custom-600` | `dark:text-primary-custom-600` |
+| **Hover buttons** | `hover:bg-background-secondary` | `dark:hover:bg-dark-bg-secondary` |
+| **Botón navegación** | `bg-primary-custom-600` | `dark:bg-dark-bg-inverse` |
+| **Badge notificación** | `bg-error-content` | `dark:bg-error-content` |
+| **Focus ring** | `focus:ring-primary-custom-400` | `dark:focus:ring-dark-border-custom` |
+| **Focus offset** | `focus:ring-offset-2` | `dark:focus:ring-offset-dark-bg-primary` |
+
+### Estados Interactivos
+
+Todos los botones incluyen:
+- **Hover**: Cambio de fondo adaptativo
+- **Active**: `scale-95` para feedback visual
+- **Focus**: Ring adaptativo con offset correcto
+- **Transiciones**: `transition-all duration-150`
+
+## Responsive Behavior
+
+| Elemento | Desktop (lg:) | Tablet (md:) | Mobile |
+|----------|---------------|--------------|--------|
+| **Altura** | 64px | 64px | 40px |
+| **Botón navegación** | Visible | Visible | Oculto |
+| **Business Logo** | 168x30px | 140x25px | Oculto |
+| **Siesa Logo Leading** | 120x30px | 100x25px | 30x30px (icono) |
+| **Nombre producto** | Visible | Visible | Oculto |
+| **Dividers** | Visibles | Visibles | Ocultos |
+| **Badge ambiente** | Texto completo | Texto completo | "Pruebas" |
+| **Botón búsqueda** | Oculto | Oculto | Visible |
+| **Avatar** | 40x40 rounded-md | 40x40 rounded-md | 32x32 rounded-full |
+| **Nombre/email** | Visibles | Visibles | Ocultos |
+| **Chevron** | Visible | Visible | Oculto |
+| **Siesa Logo Trailing** | Visible | Oculto | Oculto |
+
+## Mejores Prácticas
+
+### Hacer
+
+1. Usar la variante `responsive` (default) para adaptación automática
+2. Proporcionar siempre `userDropdown` para mostrar información del usuario
+3. Usar avatares de alta resolución (mínimo 80x80px)
+4. Mantener `productName` corto (idealmente <25 caracteres)
+5. Actualizar `notifications` dinámicamente
+6. Usar solo tokens del sistema para customización
+7. Testear estados de focus con teclado (Tab)
+8. Implementar handlers para interactividad
+
+### Evitar
+
+1. No forzar variantes a menos que sea necesario
+2. No usar textos muy largos en `productName`
+3. No olvidar `environmentBadge` en desarrollo/prueba
+4. No mezclar el navbar con otros headers
+5. No usar colores hardcodeados (hex)
+6. No omitir handlers para elementos interactivos
+
+## Archivos del Componente
+
+```
+src/components/Navbar/
+├── Navbar.tsx          # Componente principal
+├── Navbar.types.ts     # Tipos e interfaces
+├── Navbar.stories.tsx  # Stories de Storybook
+├── icons.tsx           # Iconos Heroicons Micro
+├── index.ts            # Exports
+└── README.md           # Documentación
+```
+
+## Referencias
+
+- **Figma**: [Navbar Component](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4278-18626&m=dev)
+- **Docs**:
+  - `docs/colors.md` - Sistema de colores
+  - `docs/typography.md` - Sistema tipográfico
+  - `docs/spacing.md` - Sistema de espaciado
+  - `docs/shadows.md` - Sistema de sombras
+  - `docs/dark-mode-guide.md` - Guía de dark mode
+
+## Changelog
+
+### Version 1.2.0 (2025-12-02) - Corrección Completa Siesa UI Kit Specialist
+
+**Nuevas características:**
+- Variante `tablet` añadida para soporte completo responsive
+- `showTrailingSiesaLogo` prop para controlar logo Siesa en trailing
+- Handlers de eventos: `onNavigationClick`, `onSearchClick`, `onCartClick`, `onNotificationsClick`
+- Tipos exportados: `NavbarVariant`, `UserDropdownProps`, `NotificationsProps`
+
+**Correcciones:**
+- Dark mode completo en todos los elementos con tokens del sistema
+- Focus rings adaptativos para light y dark mode
+- Botón de navegación con `shadow-button-inset` según Button de referencia
+- Badge de ambiente usa componente Badge correctamente
+- Hover states con tokens: `hover:bg-background-secondary` / `dark:hover:bg-dark-bg-secondary`
+- Fondo del navbar con tokens: `bg-background-primary` / `dark:bg-dark-bg-primary`
+
+**Mejoras:**
+- JSDoc completo con referencias `@see` a documentación
+- Stories actualizadas con ejemplos de todas las variantes
+- README actualizado con tabla de tokens y especificaciones
+
+### Version 1.1.0 (2025-11-19)
+- Corrección de colores hardcodeados
+- Añadidos focus rings adaptativos
+- Active states con scale-95
+
+### Version 1.0.0 (2025-11-18)
+- Componente inicial con soporte responsive
+- Dark mode básico
+- Badges de notificación
+
+---
+
+**Mantenido por**: Equipo Siesa UI Kit
+**Última actualización**: 2025-12-02