siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/Navbar/Navbar.types.ts

@@ -1,219 +1,219 @@
-import type { ReactNode } from 'react';
-
-/**
- * Variante de dispositivo del Navbar
- * - `responsive`: Se adapta automáticamente al viewport (por defecto)
- * - `desktop`: Versión completa (≥1024px) con todos los elementos
- * - `tablet`: Versión tablet (≥768px) con elementos reducidos
- * - `mobile`: Versión simplificada (<768px) con logo icono y avatar circular
- *
- * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4278-18626
- */
-export type NavbarVariant = 'responsive' | 'desktop' | 'tablet' | 'mobile';
-
-/**
- * Datos del dropdown de usuario
- *
- * @example
- * ```tsx
- * const userDropdown: UserDropdownProps = {
- *   avatar: '/path/to/avatar.jpg',
- *   name: 'Juan Pérez',
- *   email: 'juan@ejemplo.com',
- *   onMenuClick: () => setMenuOpen(true),
- * };
- * ```
- */
-export interface UserDropdownProps {
-  /**
-   * URL del avatar del usuario
-   * Recomendado: mínimo 80x80px para retina
-   */
-  avatar: string;
-
-  /**
-   * Nombre del usuario (se muestra en desktop/tablet)
-   */
-  name: string;
-
-  /**
-   * Email del usuario (se muestra en desktop/tablet)
-   */
-  email?: string;
-
-  /**
-   * Rol del usuario (alternativa a email, ej: "Administrador")
-   */
-  role?: string;
-
-  /**
-   * Handler para click en el dropdown de usuario
-   */
-  onMenuClick?: () => void;
-}
-
-/**
- * Configuración de badges de notificación
- *
- * @example
- * ```tsx
- * const notifications: NotificationsProps = {
- *   cart: 15,      // Muestra badge con "15"
- *   bell: true,    // Muestra dot de notificación
- * };
- * ```
- */
-export interface NotificationsProps {
-  /**
-   * Número de items en el carrito
-   * Si es > 99, muestra "+99"
-   */
-  cart?: number;
-
-  /**
-   * Muestra dot de notificación en la campana
-   */
-  bell?: boolean;
-}
-
-/**
- * Props del componente Navbar
- *
- * Barra de navegación principal con soporte completo para responsive design y dark mode.
- * Incluye logo, nombre de producto, badge de ambiente, botones de acción y dropdown de usuario.
- *
- * **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
- * - Focus rings adaptativos para light y dark mode
- * - Tipografía del sistema: Heading/Tiny (20px Bold), Paragraph/Small (14px), Paragraph/Tiny (12px)
- * - Spacing del sistema: 4px, 8px, 12px, 16px, 32px
- *
- * @see docs/colors.md - Sistema de colores y tokens dark mode
- * @see docs/typography.md - Sistema tipográfico (Heading, Paragraph)
- * @see docs/spacing.md - Sistema de espaciado
- * @see docs/shadows.md - Sistema de sombras (button-inset)
- */
-export interface NavbarProps {
-  /**
-   * Logo del negocio/cliente (componente o imagen)
-   * Solo visible en desktop/tablet
-   *
-   * @default Logo por defecto de la carpeta public
-   */
-  logo?: ReactNode;
-
-  /**
-   * Logo de Siesa personalizado
-   * Si no se proporciona, usa el logo por defecto según variante
-   *
-   * @default Logo Siesa de la carpeta public
-   */
-  siesaLogo?: ReactNode;
-
-  /**
-   * Nombre del producto que aparece después del logo
-   * Solo visible en desktop/tablet (se oculta en mobile)
-   *
-   * @default 'Nombre Producto'
-   */
-  productName?: string;
-
-  /**
-   * Badge de ambiente/entorno (ej: "Ambiente de Pruebas")
-   * En mobile muestra versión corta ("Pruebas")
-   */
-  environmentBadge?: string;
-
-  /**
-   * Contenido del dropdown de usuario
-   */
-  userDropdown?: UserDropdownProps;
-
-  /**
-   * Elementos de acción adicionales en la barra (botones, iconos, etc.)
-   * Se muestran a la derecha después del dropdown de usuario
-   */
-  actions?: ReactNode;
-
-  /**
-   * Configuración de badges de notificación para los botones
-   */
-  notifications?: NotificationsProps;
-
-  /**
-   * Clases CSS adicionales para el contenedor del navbar
-   */
-  className?: string;
-
-  /**
-   * Modo de visualización del navbar
-   * - `responsive`: Se adapta automáticamente al viewport
-   * - `desktop`: Versión completa (1360x64px)
-   * - `tablet`: Versión tablet (1024x64px)
-   * - `mobile`: Versión compacta (428x40px)
-   *
-   * @default 'responsive'
-   */
-  variant?: NavbarVariant;
-
-  /**
-   * Ocultar botones de acción (carrito, notificaciones, búsqueda)
-   *
-   * @default false
-   */
-  hideActionButtons?: boolean;
-
-  /**
-   * Elemento leading personalizado (reemplaza el botón de navegación por defecto)
-   * Solo visible en desktop/tablet
-   */
-  leadingAction?: ReactNode;
-
-  /**
-   * Mostrar Business Logo en el leading (lado izquierdo)
-   * Solo visible en desktop/tablet
-   *
-   * @default false
-   */
-  showBusinessLogo?: boolean;
-
-  /**
-   * Mostrar Logo de Siesa en el leading (lado izquierdo)
-   * Solo visible en desktop/tablet (en mobile siempre muestra el icono)
-   *
-   * @default true
-   */
-  showSiesaLogoLeading?: boolean;
-
-  /**
-   * Mostrar Logo de Siesa en el trailing (lado derecho)
-   * Solo visible en desktop/tablet
-   *
-   * @default false
-   */
-  showSiesaLogoTrailing?: boolean;
-
-  /**
-   * Handler para click en el botón de navegación (flecha izquierda)
-   * Solo visible en desktop/tablet cuando no hay leadingAction
-   */
-  onNavigationClick?: () => void;
-
-  /**
-   * Handler para click en el botón de búsqueda
-   * Solo visible en mobile
-   */
-  onSearchClick?: () => void;
-
-  /**
-   * Handler para click en el botón de carrito
-   */
-  onCartClick?: () => void;
-
-  /**
-   * Handler para click en el botón de notificaciones
-   */
-  onNotificationsClick?: () => void;
-}
+import type { ReactNode } from 'react';
+
+/**
+ * Variante de dispositivo del Navbar
+ * - `responsive`: Se adapta automáticamente al viewport (por defecto)
+ * - `desktop`: Versión completa (≥1024px) con todos los elementos
+ * - `tablet`: Versión tablet (≥768px) con elementos reducidos
+ * - `mobile`: Versión simplificada (<768px) con logo icono y avatar circular
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4278-18626
+ */
+export type NavbarVariant = 'responsive' | 'desktop' | 'tablet' | 'mobile';
+
+/**
+ * Datos del dropdown de usuario
+ *
+ * @example
+ * ```tsx
+ * const userDropdown: UserDropdownProps = {
+ *   avatar: '/path/to/avatar.jpg',
+ *   name: 'Juan Pérez',
+ *   email: 'juan@ejemplo.com',
+ *   onMenuClick: () => setMenuOpen(true),
+ * };
+ * ```
+ */
+export interface UserDropdownProps {
+  /**
+   * URL del avatar del usuario
+   * Recomendado: mínimo 80x80px para retina
+   */
+  avatar: string;
+
+  /**
+   * Nombre del usuario (se muestra en desktop/tablet)
+   */
+  name: string;
+
+  /**
+   * Email del usuario (se muestra en desktop/tablet)
+   */
+  email?: string;
+
+  /**
+   * Rol del usuario (alternativa a email, ej: "Administrador")
+   */
+  role?: string;
+
+  /**
+   * Handler para click en el dropdown de usuario
+   */
+  onMenuClick?: () => void;
+}
+
+/**
+ * Configuración de badges de notificación
+ *
+ * @example
+ * ```tsx
+ * const notifications: NotificationsProps = {
+ *   cart: 15,      // Muestra badge con "15"
+ *   bell: true,    // Muestra dot de notificación
+ * };
+ * ```
+ */
+export interface NotificationsProps {
+  /**
+   * Número de items en el carrito
+   * Si es > 99, muestra "+99"
+   */
+  cart?: number;
+
+  /**
+   * Muestra dot de notificación en la campana
+   */
+  bell?: boolean;
+}
+
+/**
+ * Props del componente Navbar
+ *
+ * Barra de navegación principal con soporte completo para responsive design y dark mode.
+ * Incluye logo, nombre de producto, badge de ambiente, botones de acción y dropdown de usuario.
+ *
+ * **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
+ * - Focus rings adaptativos para light y dark mode
+ * - Tipografía del sistema: Heading/Tiny (20px Bold), Paragraph/Small (14px), Paragraph/Tiny (12px)
+ * - Spacing del sistema: 4px, 8px, 12px, 16px, 32px
+ *
+ * @see docs/colors.md - Sistema de colores y tokens dark mode
+ * @see docs/typography.md - Sistema tipográfico (Heading, Paragraph)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras (button-inset)
+ */
+export interface NavbarProps {
+  /**
+   * Logo del negocio/cliente (componente o imagen)
+   * Solo visible en desktop/tablet
+   *
+   * @default Logo por defecto de la carpeta public
+   */
+  logo?: ReactNode;
+
+  /**
+   * Logo de Siesa personalizado
+   * Si no se proporciona, usa el logo por defecto según variante
+   *
+   * @default Logo Siesa de la carpeta public
+   */
+  siesaLogo?: ReactNode;
+
+  /**
+   * Nombre del producto que aparece después del logo
+   * Solo visible en desktop/tablet (se oculta en mobile)
+   *
+   * @default 'Nombre Producto'
+   */
+  productName?: string;
+
+  /**
+   * Badge de ambiente/entorno (ej: "Ambiente de Pruebas")
+   * En mobile muestra versión corta ("Pruebas")
+   */
+  environmentBadge?: string;
+
+  /**
+   * Contenido del dropdown de usuario
+   */
+  userDropdown?: UserDropdownProps;
+
+  /**
+   * Elementos de acción adicionales en la barra (botones, iconos, etc.)
+   * Se muestran a la derecha después del dropdown de usuario
+   */
+  actions?: ReactNode;
+
+  /**
+   * Configuración de badges de notificación para los botones
+   */
+  notifications?: NotificationsProps;
+
+  /**
+   * Clases CSS adicionales para el contenedor del navbar
+   */
+  className?: string;
+
+  /**
+   * Modo de visualización del navbar
+   * - `responsive`: Se adapta automáticamente al viewport
+   * - `desktop`: Versión completa (1360x64px)
+   * - `tablet`: Versión tablet (1024x64px)
+   * - `mobile`: Versión compacta (428x40px)
+   *
+   * @default 'responsive'
+   */
+  variant?: NavbarVariant;
+
+  /**
+   * Ocultar botones de acción (carrito, notificaciones, búsqueda)
+   *
+   * @default false
+   */
+  hideActionButtons?: boolean;
+
+  /**
+   * Elemento leading personalizado (reemplaza el botón de navegación por defecto)
+   * Solo visible en desktop/tablet
+   */
+  leadingAction?: ReactNode;
+
+  /**
+   * Mostrar Business Logo en el leading (lado izquierdo)
+   * Solo visible en desktop/tablet
+   *
+   * @default false
+   */
+  showBusinessLogo?: boolean;
+
+  /**
+   * Mostrar Logo de Siesa en el leading (lado izquierdo)
+   * Solo visible en desktop/tablet (en mobile siempre muestra el icono)
+   *
+   * @default true
+   */
+  showSiesaLogoLeading?: boolean;
+
+  /**
+   * Mostrar Logo de Siesa en el trailing (lado derecho)
+   * Solo visible en desktop/tablet
+   *
+   * @default false
+   */
+  showSiesaLogoTrailing?: boolean;
+
+  /**
+   * Handler para click en el botón de navegación (flecha izquierda)
+   * Solo visible en desktop/tablet cuando no hay leadingAction
+   */
+  onNavigationClick?: () => void;
+
+  /**
+   * Handler para click en el botón de búsqueda
+   * Solo visible en mobile
+   */
+  onSearchClick?: () => void;
+
+  /**
+   * Handler para click en el botón de carrito
+   */
+  onCartClick?: () => void;
+
+  /**
+   * Handler para click en el botón de notificaciones
+   */
+  onNotificationsClick?: () => void;
+}