siesa-ui-kit 1.0.1 → 1.0.2

package/src/components/NavigationRailItem/README.md

@@ -0,0 +1,476 @@
+# NavigationRailItem
+
+Componente individual de item para la barra de navegación vertical (NavigationRail) del sistema de diseño Siesa UI Kit.
+
+## 📋 Descripción
+
+`NavigationRailItem` es un componente independiente que representa un item seleccionable dentro de una `NavigationRail`. Proporciona acceso rápido a destinos principales mediante un icono, label opcional y badges de notificación.
+
+**Implementación pixel-perfect** según Figma (node 4294-22931) con soporte completo para todos los estados, dark mode y accesibilidad.
+
+## 🎯 Características
+
+- ✅ **Ancho fijo de 56px** según especificaciones de Figma
+- ✅ **Estados completos**: Enabled, Hover, Selected, Focus, Disabled
+- ✅ **Badges de notificación**: Dot simple o contador numérico (99+ para >99)
+- ✅ **Tipografía del sistema**: Label XXSmall (10px Bold, leading 12px)
+- ✅ **Dark Mode completo**: Colores invertidos en todos los estados
+- ✅ **Focus rings adaptativos**: Accesibilidad y keyboard navigation
+- ✅ **Iconos flexibles**: Soporta cualquier librería (Heroicons, React Icons, etc.)
+- ✅ **ARIA completo**: aria-label, aria-current, aria-disabled
+- ✅ **Tokens del sistema**: NO colores hardcodeados
+
+## 📐 Especificaciones de Figma
+
+### Dimensiones
+- **Ancho**: 56px (w-14)
+- **Altura**: Auto (flex-col)
+- **Icon container**: 32px altura, 16px padding horizontal
+- **Gap icon-label**: 4px (gap-1)
+- **Border radius icon**: 9999px (rounded-full)
+
+### Estados Visuales
+
+| Estado | Background | Icon Color | Label Color | Cursor |
+|--------|-----------|-----------|-----------|--------|
+| **Enabled** | Transparent | content-primary | content-primary | pointer |
+| **Hover** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
+| **Selected** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
+| **Focus** | primary-custom-100 + ring | primary-custom-600 | content-primary | pointer |
+| **Disabled** | Transparent (opacity 55%) | content-tertiary | content-tertiary | not-allowed |
+
+### Badge
+
+- **Tamaño**: 13x13px
+- **Border radius**: rounded-full (9999px)
+- **Posición**: Absoluta (-top-0.5, left-[34px])
+- **Color**: Red 700 (#b91c1c)
+- **Tipografía**: 10px Bold
+- **Tipos**:
+  - **Dot**: Badge simple sin número
+  - **Contador**: Número 1-99+
+
+### Focus Ring (Accesibilidad)
+
+Según Figma node 4294-22931, el focus ring tiene estas características:
+
+```css
+ring: 2px (#60b6fa)
+offset: 2px (#dbeefe)
+shadow: 0px_0px_0px_2px_#dbeefe, 0px_1px_2px_0px_rgba(0,0,0,0.05), 0px_0px_0px_4px_#60b6fa
+```
+
+## 🎨 Dark Mode
+
+El componente invierte automáticamente sus colores en dark mode:
+
+- **Background**: bg-primary-custom-600/30
+- **Icon**: text-white (selected), dark-content-primary (default)
+- **Label**: dark-content-primary
+- **Focus ring**: dark-border-custom
+
+Usa la estrategia `class` de Tailwind CSS:
+
+```tsx
+<div className="dark">
+  <NavigationRailItem label="Inicio" selected={true} />
+</div>
+```
+
+## 💻 Uso
+
+### Instalación
+
+```bash
+npm install siesa-ui-kit
+```
+
+### Ejemplo Básico
+
+```tsx
+import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
+import { HomeIcon } from '@heroicons/react/24/outline';
+
+export function App() {
+  return (
+    <NavigationRailItem
+      id="home"
+      icon={<HomeIcon />}
+      label="Inicio"
+      selected={true}
+      onClick={() => navigate('/')}
+    />
+  );
+}
+```
+
+### Con Badge
+
+```tsx
+import { BellIcon } from '@heroicons/react/24/outline';
+
+<NavigationRailItem
+  id="notifications"
+  icon={<BellIcon />}
+  label="Notificaciones"
+  badgeCount={5}
+/>
+```
+
+### Deshabilitado
+
+```tsx
+import { StarIcon } from '@heroicons/react/24/outline';
+
+<NavigationRailItem
+  id="premium"
+  icon={<StarIcon />}
+  label="Premium"
+  disabled={true}
+/>
+```
+
+### Solo Icono
+
+```tsx
+<NavigationRailItem
+  id="home"
+  icon={<HomeIcon />}
+  label="Inicio"
+  showLabelText={false}
+/>
+```
+
+### En un NavigationRail
+
+```tsx
+import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
+import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
+
+export function Navbar() {
+  const [selected, setSelected] = React.useState('home');
+
+  const items = [
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'notifications', icon: <BellIcon />, label: 'Notificaciones', badgeCount: 3 },
+  ];
+
+  return (
+    <nav className="flex gap-3">
+      {items.map((item) => (
+        <NavigationRailItem
+          key={item.id}
+          id={item.id}
+          icon={item.icon}
+          label={item.label}
+          badgeCount={item.badgeCount}
+          selected={selected === item.id}
+          onClick={() => setSelected(item.id)}
+        />
+      ))}
+    </nav>
+  );
+}
+```
+
+## 📖 Props
+
+### `icon` (Required)
+
+```typescript
+icon: ReactNode
+```
+
+Icono a mostrar. Tamaño recomendado: 16x16px.
+
+**Ejemplos:**
+- Heroicons: `<HomeIcon />`
+- React Icons: `<FiHome />`
+- SVG inline: `<svg>...</svg>`
+
+### `label` (Required)
+
+```typescript
+label: string
+```
+
+Texto del label que aparece debajo del icono. Se muestra en tipografía Label XXSmall (10px Bold).
+
+### `selected`
+
+```typescript
+selected?: boolean
+// default: false
+```
+
+Si el item está seleccionado actualmente. Cambia el background a primary-custom-100 y el icono a primary-custom-600.
+
+### `disabled`
+
+```typescript
+disabled?: boolean
+// default: false
+```
+
+Si el item está deshabilitado. Reduce la opacidad a 55%, cambia el cursor a not-allowed y desactiva la interactividad.
+
+### `badge`
+
+```typescript
+badge?: boolean
+// default: false
+```
+
+Mostrar badge de notificación simple (dot rojo). Se ignora si `badgeCount` está definido.
+
+### `badgeCount`
+
+```typescript
+badgeCount?: number
+```
+
+Número a mostrar en el badge. Reemplaza el dot simple. Si es mayor a 99, muestra "99+".
+
+### `onClick`
+
+```typescript
+onClick?: () => void
+```
+
+Callback cuando se hace click en el item.
+
+**Nota:** Se ejecuta incluso si el item está disabled (pero el botón no es clickeable).
+
+### `ariaLabel`
+
+```typescript
+ariaLabel?: string
+```
+
+Label para accesibilidad (ARIA). Si no se proporciona, usa el valor de `label`.
+
+**Ejemplo:**
+```tsx
+<NavigationRailItem
+  label="Inicio"
+  ariaLabel="Ir a la página de inicio del sitio web"
+/>
+```
+
+### `id`
+
+```typescript
+id?: string
+```
+
+ID único del item. Se usa para identificarlo en navegación y se añade como atributo `data-item-id`.
+
+**Ejemplo:**
+```tsx
+<NavigationRailItem id="home" label="Inicio" />
+// Genera: <button data-item-id="home">...</button>
+```
+
+### `showLabelText`
+
+```typescript
+showLabelText?: boolean
+// default: true
+```
+
+Si el label debe ser visible. Útil para crear variaciones icon-only.
+
+### `showIcon`
+
+```typescript
+showIcon?: boolean
+// default: true
+```
+
+Si el icono debe ser visible. Útil para crear variaciones label-only.
+
+### `className`
+
+```typescript
+className?: string
+// default: ''
+```
+
+Clases CSS adicionales personalizadas.
+
+## 🎨 Diseño del Sistema
+
+### Colores (según `docs/colors.md`)
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `primary-custom-600` | #0e79fd | Color principal del icono en estados selected/hover |
+| `primary-custom-100` | #dbeefe | Background del icon container en hover/selected |
+| `content-primary` | - | Color del texto y iconos por defecto |
+| `content-tertiary` | - | Color del texto deshabilitado |
+| `red-700` | #b91c1c | Color del badge |
+
+### Tipografía (según `docs/typography.md`)
+
+| Elemento | Estilo | Valores |
+|----------|--------|--------|
+| Label | Label XXSmall | 10px Bold, leading 12px |
+| Badge | Label Tiny | 10px Bold |
+
+### Espaciado (según `docs/spacing.md`)
+
+| Elemento | Espaciado |
+|----------|-----------|
+| Icon container padding | px-4 py-1 (16px h, 4px v) |
+| Gap icon-label | gap-1 (4px) |
+| Contenedor padding | px-0.5 (2px) |
+
+### Sombras (según `docs/shadows.md`)
+
+| Estado | Sombra |
+|--------|--------|
+| Focus | shadow-[0px_0px_0px_2px_rgba(219,238,254,1),0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_rgba(96,182,250,1)] |
+
+## ♿ Accesibilidad
+
+El componente cumple con estándares WCAG:
+
+- ✅ **ARIA Labels**: `aria-label` personalizable
+- ✅ **ARIA State**: `aria-current="page"` cuando está selected
+- ✅ **Disabled State**: `aria-disabled` y `disabled` attributes
+- ✅ **Keyboard Navigation**: Focus ring adaptativo (2px)
+- ✅ **Color Contrast**: Ratios WCAG AA/AAA en light y dark mode
+- ✅ **Touch Targets**: Mínimo 44x44px (56x56px real)
+
+### Keyboard Navigation
+
+```html
+<!-- Tab para navegar -->
+<!-- Enter/Space para activar -->
+<!-- Navega entre items del NavigationRail -->
+```
+
+## 🔄 Relación con Otros Componentes
+
+### NavigationRail
+
+`NavigationRailItem` está diseñado para usarse dentro de `NavigationRail`, aunque puede usarse de forma independiente.
+
+```tsx
+import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
+
+<NavigationRail
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', selected: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  ]}
+/>
+```
+
+### Button
+
+Comparte la misma estructura de estados y tokens que el componente `Button`:
+
+- Estados similares (default, hover, selected, focus, disabled)
+- Tipografía del sistema (aunque tamaños diferentes)
+- Focus rings adaptativos
+- Dark mode completo
+
+## 🧪 Testing
+
+### Data Attributes
+
+Para facilitar testing:
+
+```html
+<button data-item-id="home" data-testid="navigation-rail-item-home" data-badge>
+  ...
+</button>
+```
+
+### Ejemplos de Tests
+
+```typescript
+// Vitest / Jest
+import { render, screen } from '@testing-library/react';
+import { NavigationRailItem } from './NavigationRailItem';
+import { HomeIcon } from '@heroicons/react/24/outline';
+
+describe('NavigationRailItem', () => {
+  it('renders with label', () => {
+    render(<NavigationRailItem icon={<HomeIcon />} label="Inicio" id="home" />);
+    expect(screen.getByText('Inicio')).toBeInTheDocument();
+  });
+
+  it('shows badge count', () => {
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        badgeCount={5}
+      />
+    );
+    expect(screen.getByText('5')).toBeInTheDocument();
+  });
+
+  it('disables when disabled prop is true', () => {
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        disabled={true}
+      />
+    );
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  it('calls onClick when clicked', () => {
+    const handleClick = vi.fn();
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        onClick={handleClick}
+      />
+    );
+    screen.getByRole('button').click();
+    expect(handleClick).toHaveBeenCalled();
+  });
+});
+```
+
+## 📚 Referencias
+
+- **Figma**: [node 4294-22931](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931)
+- **Docs de colores**: [docs/colors.md](../../docs/colors.md)
+- **Docs de tipografía**: [docs/typography.md](../../docs/typography.md)
+- **Docs de espaciado**: [docs/spacing.md](../../docs/spacing.md)
+- **Docs de sombras**: [docs/shadows.md](../../docs/shadows.md)
+- **Componente NavigationRail**: [NavigationRail](../NavigationRail/README.md)
+- **Componente Button**: [Button](../Button/README.md) (referencia de estructura)
+
+## 📝 Changelog
+
+### v1.0.0 (Inicial)
+
+- ✨ Componente NavigationRailItem creado
+- ✨ Todos los estados implementados (Enabled, Hover, Selected, Focus, Disabled)
+- ✨ Badges de notificación (dot y contador)
+- ✨ Dark Mode completo
+- ✨ Accesibilidad WCAG completa
+- ✨ Stories completas en Storybook
+- ✨ TypeScript types
+- ✨ JSDoc completo
+- ✨ README documentado
+
+## 📄 Licencia
+
+Parte del Sistema de Diseño Siesa UI Kit. © 2024 Siesa.
+
+---
+
+**Última actualización**: 24 de diciembre de 2024

package/src/components/NavigationRailItem/index.ts

@@ -0,0 +1,2 @@
+export { NavigationRailItem } from './NavigationRailItem';
+export type { NavigationRailItemProps, NavigationRailItemState } from './NavigationRailItem.types';