siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailItem/NavigationRailItem.types.ts

@@ -1,167 +1,175 @@
-import type { ReactNode } from 'react';
-
-/**
- * Props para NavigationRailItem
- *
- * Componente independiente para items individuales de NavigationRail.
- * Implementación pixel-perfect según Figma (node 4294-22931).
- *
- * **Estados:**
- * - `Enabled`: Estado normal del item
- * - `Hover`: Overlay de color en el icon container
- * - `Selected`: Background con overlay según Figma
- * - `Focus`: Focus ring de 4px (#60b6fa) con offset de 2px (#dbeefe)
- * - `Disabled`: Opacity 55% con pointer-events-none
- *
- * **Especificaciones de Figma:**
- * - Ancho: 56px (w-14)
- * - Altura: auto (flex-col)
- * - Gap: 4px entre icon y label
- * - Padding: 2px horizontal, 0px vertical (px-0.5)
- * - Border radius: 9999px (rounded-full) en icon container
- * - Tipografía label: Label XXSmall (10px Bold, leading 12px)
- * - Icono: 16x16px
- *
- * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
- * @see docs/colors.md - Sistema de colores
- * @see docs/typography.md - Sistema tipográfico (Label XXSmall)
- * @see docs/spacing.md - Sistema de espaciado
- * @see docs/shadows.md - Sistema de sombras (focus ring)
- */
-export interface NavigationRailItemProps {
-  /**
-   * Icono a mostrar en el item
-   * Tamaño recomendado: 16x16px
-   * Tipos compatibles: ReactNode, SVG, Heroicons, etc.
-   *
-   * @example
-   * ```tsx
-   * import { HomeIcon } from '@heroicons/react/24/outline';
-   * <NavigationRailItem icon={<HomeIcon />} />
-   * ```
-   */
-  icon: ReactNode;
-
-  /**
-   * Label/texto del item de navegación
-   * Se muestra debajo del icono en tipografía Label XXSmall
-   *
-   * @example
-   * <NavigationRailItem label="Inicio" />
-   */
-  label: string;
-
-  /**
-   * Si el item está seleccionado actualmente
-   *
-   * Estado visual:
-   * - Background: bg-primary-custom-100 (#dbeefe) con overlay rgba(0,0,0,0.024)
-   * - Icono: text-primary-custom-600 (#0e79fd)
-   * - Label: text-content-primary
-   *
-   * @default false
-   */
-  selected?: boolean;
-
-  /**
-   * Si el item está deshabilitado
-   *
-   * Estado visual:
-   * - Opacity: 55%
-   * - Cursor: not-allowed
-   * - Pointer-events: none
-   *
-   * @default false
-   */
-  disabled?: boolean;
-
-  /**
-   * Mostrar badge de notificación (dot rojo)
-   *
-   * El badge se posiciona en la esquina superior derecha del icon container.
-   * Tamaño: 13x13px
-   * Color: #b91c1c (red-700)
-   * Posición: left-[34px], top-[-3px]
-   *
-   * @default false
-   */
-  badge?: boolean;
-
-  /**
-   * Número a mostrar en el badge (reemplaza el dot simple)
-   *
-   * Si el número es mayor a 99, muestra "99+"
-   * Tipografía: 10px Bold
-   * Color: white (#ffffff)
-   *
-   * @example
-   * <NavigationRailItem badgeCount={5} />  // Muestra: 5
-   * <NavigationRailItem badgeCount={150} /> // Muestra: 99+
-   */
-  badgeCount?: number;
-
-  /**
-   * Handler para evento click del item
-   *
-   * Se ejecuta cuando el usuario hace click en el item,
-   * incluso si está en estado selected.
-   */
-  onClick?: () => void;
-
-  /**
-   * Label para accesibilidad (ARIA-label)
-   *
-   * Si no se proporciona, usa el valor de `label`
-   *
-   * @example
-   * <NavigationRailItem label="Inicio" ariaLabel="Ir a la página de inicio" />
-   */
-  ariaLabel?: string;
-
-  /**
-   * ID único del item
-   *
-   * Usado para identificar el item en callbacks y para navegación.
-   * Se añade como atributo data-item-id en el elemento DOM.
-   *
-   * @example
-   * <NavigationRailItem id="home" label="Inicio" />
-   */
-  id?: string;
-
-  /**
-   * Mostrar el label del texto
-   *
-   * Si es false, solo se muestra el icono
-   *
-   * @default true
-   */
-  showLabelText?: boolean;
-
-  /**
-   * Mostrar icono
-   *
-   * Si es false, solo se muestra el label
-   *
-   * @default true
-   */
-  showIcon?: boolean;
-
-  /**
-   * Clases CSS adicionales personalizadas
-   *
-   * Se aplican al contenedor principal (button)
-   */
-  className?: string;
-}
-
-/**
- * Estados posibles del componente según Figma
- *
- * - `Enabled`: Estado normal, sin interacción
- * - `Hover`: Mouse over el item
- * - `Selected`: Item actualmente seleccionado
- * - `Focus`: Keyboard focus (accesibilidad)
- * - `Disabled`: Item deshabilitado, no interactivo
- */
-export type NavigationRailItemState = 'Enabled' | 'Hover' | 'Selected' | 'Focus' | 'Disabled';
+import type { ReactNode } from 'react';
+
+/**
+ * Props para NavigationRailItem
+ *
+ * Componente independiente para items individuales de NavigationRail.
+ * Implementación pixel-perfect según Figma (node 4294-22931).
+ *
+ * **Estados:**
+ * - `Enabled`: Estado normal del item
+ * - `Hover`: Overlay de color en el icon container
+ * - `Selected`: Background con overlay según Figma
+ * - `Focus`: Focus ring de 4px (#60b6fa) con offset de 2px (#dbeefe)
+ * - `Disabled`: Opacity 55% con pointer-events-none
+ *
+ * **Especificaciones de Figma:**
+ * - Ancho: 56px (w-14)
+ * - Altura: auto (flex-col)
+ * - Gap: 4px entre icon y label
+ * - Padding: 2px horizontal, 0px vertical (px-0.5)
+ * - Border radius: 9999px (rounded-full) en icon container
+ * - Tipografía label: Label XXSmall (10px Bold, leading 12px)
+ * - Icono: 16x16px
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label XXSmall)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras (focus ring)
+ */
+export interface NavigationRailItemProps {
+  /**
+   * Icono a mostrar en el item
+   * Tamaño recomendado: 16x16px
+   * Tipos compatibles: ReactNode, SVG, Heroicons, etc.
+   *
+   * @example
+   * ```tsx
+   * import { HomeIcon } from '@heroicons/react/24/outline';
+   * <NavigationRailItem icon={<HomeIcon />} />
+   * ```
+   */
+  icon: ReactNode;
+
+  /**
+   * Label/texto del item de navegación
+   * Se muestra debajo del icono en tipografía Label XXSmall
+   *
+   * @example
+   * <NavigationRailItem label="Inicio" />
+   */
+  label: string;
+
+  /**
+   * Si el item está seleccionado actualmente
+   *
+   * Estado visual:
+   * - Background: bg-primary-custom-100 (#dbeefe) con overlay rgba(0,0,0,0.024)
+   * - Icono: text-primary-custom-600 (#0e79fd)
+   * - Label: text-content-primary
+   *
+   * @default false
+   */
+  selected?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   *
+   * Estado visual:
+   * - Opacity: 55%
+   * - Cursor: not-allowed
+   * - Pointer-events: none
+   *
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Mostrar badge de notificación (dot rojo)
+   *
+   * El badge se posiciona en la esquina superior derecha del icon container.
+   * Tamaño: 13x13px
+   * Color: #b91c1c (red-700)
+   * Posición: left-[34px], top-[-3px]
+   *
+   * @default false
+   */
+  badge?: boolean;
+
+  /**
+   * Número a mostrar en el badge (reemplaza el dot simple)
+   *
+   * Si el número es mayor a 99, muestra "99+"
+   * Tipografía: 10px Bold
+   * Color: white (#ffffff)
+   *
+   * @example
+   * <NavigationRailItem badgeCount={5} />  // Muestra: 5
+   * <NavigationRailItem badgeCount={150} /> // Muestra: 99+
+   */
+  badgeCount?: number;
+
+  /**
+   * Handler para evento click del item
+   *
+   * Se ejecuta cuando el usuario hace click en el item,
+   * incluso si está en estado selected.
+   */
+  onClick?: () => void;
+
+  /**
+   * Handler para evento mouse enter del item
+   *
+   * Se ejecuta cuando el cursor entra en el área del item.
+   * Útil para mostrar paneles o menús contextuales.
+   */
+  onMouseEnter?: () => void;
+
+  /**
+   * Label para accesibilidad (ARIA-label)
+   *
+   * Si no se proporciona, usa el valor de `label`
+   *
+   * @example
+   * <NavigationRailItem label="Inicio" ariaLabel="Ir a la página de inicio" />
+   */
+  ariaLabel?: string;
+
+  /**
+   * ID único del item
+   *
+   * Usado para identificar el item en callbacks y para navegación.
+   * Se añade como atributo data-item-id en el elemento DOM.
+   *
+   * @example
+   * <NavigationRailItem id="home" label="Inicio" />
+   */
+  id?: string;
+
+  /**
+   * Mostrar el label del texto
+   *
+   * Si es false, solo se muestra el icono
+   *
+   * @default true
+   */
+  showLabelText?: boolean;
+
+  /**
+   * Mostrar icono
+   *
+   * Si es false, solo se muestra el label
+   *
+   * @default true
+   */
+  showIcon?: boolean;
+
+  /**
+   * Clases CSS adicionales personalizadas
+   *
+   * Se aplican al contenedor principal (button)
+   */
+  className?: string;
+}
+
+/**
+ * Estados posibles del componente según Figma
+ *
+ * - `Enabled`: Estado normal, sin interacción
+ * - `Hover`: Mouse over el item
+ * - `Selected`: Item actualmente seleccionado
+ * - `Focus`: Keyboard focus (accesibilidad)
+ * - `Disabled`: Item deshabilitado, no interactivo
+ */
+export type NavigationRailItemState = 'Enabled' | 'Hover' | 'Selected' | 'Focus' | 'Disabled';