siesa-ui-kit 1.0.2 → 1.0.3

package/src/components/NavigationRailItem/README.md

@@ -1,476 +0,0 @@
-# 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

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