siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Notification/Notification.types.ts

@@ -0,0 +1,142 @@
+/**
+ * Props del componente Notification
+ *
+ * Badge de notificación para mostrar alertas, mensajes o notificaciones pendientes.
+ * Alineado pixel-perfect con el diseño de Figma.
+ *
+ * @see src/components/Notification/Notification.tsx - Implementación del componente
+ * @see docs/colors.md - Sistema de colores (token content-extensions-red)
+ * @see docs/typography.md - Sistema tipográfico (Label/XXSmall)
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4310-22651
+ *
+ * @example
+ * ```tsx
+ * // Badge simple (punto)
+ * const simpleProps: NotificationProps = {};
+ *
+ * // Badge con número
+ * const withCountProps: NotificationProps = {
+ *   count: 5,
+ *   color: 'red',
+ * };
+ *
+ * // Como overlay
+ * <button className="relative">
+ *   <Icon />
+ *   <Notification count={3} className="absolute -top-1 -right-1" />
+ * </button>
+ * ```
+ */
+export interface NotificationProps {
+  /**
+   * Número de notificaciones a mostrar
+   *
+   * **Comportamiento:**
+   * - `undefined`: Muestra badge simple (punto rojo de 8px)
+   * - `1-99`: Muestra el número exacto en el badge
+   * - `100+`: Muestra "99+" en el badge
+   * - `0` o menor: Muestra badge simple (punto)
+   *
+   * **Nota:** El badge ajusta su ancho automáticamente según el contenido,
+   * con un mínimo de 16px y padding de 4px horizontal.
+   *
+   * @example
+   * ```tsx
+   * <Notification />              // Punto rojo simple
+   * <Notification count={5} />    // Muestra "5"
+   * <Notification count={99} />   // Muestra "99"
+   * <Notification count={150} />  // Muestra "99+"
+   * <Notification count={0} />    // Punto rojo simple
+   * ```
+   *
+   * @see src/components/Notification/Notification.tsx:93-123 - Renderizado con número
+   */
+  count?: number;
+
+  /**
+   * Color del badge
+   *
+   * Define el color de fondo del badge. Permite personalizar según el contexto
+   * o tipo de notificación.
+   *
+   * **Colores disponibles:**
+   * - `red` (default): Notificaciones de error, alertas críticas
+   * - `orange`: Advertencias importantes
+   * - `yellow`: Avisos, atención requerida
+   * - `green`: Notificaciones positivas, éxito
+   * - `blue`: Información general
+   * - `purple`: Notificaciones especiales o premium
+   * - `zinc`: Notificaciones neutras
+   * - Y 15+ colores adicionales de Tailwind
+   *
+   * **Nota:** El texto siempre será blanco para mantener contraste adecuado.
+   *
+   * @default 'red'
+   *
+   * @example
+   * ```tsx
+   * <Notification count={5} color="red" />      // Error/Crítico
+   * <Notification count={2} color="orange" />   // Advertencia
+   * <Notification count={8} color="green" />    // Éxito
+   * <Notification count={3} color="blue" />     // Info
+   * <Notification count={1} color="purple" />   // Especial
+   * ```
+   *
+   * @see src/components/Button/Button.tsx:220-244 - Referencia de colores
+   */
+  color?: 'zinc' | 'red' | 'orange' | 'amber' | 'yellow' | 'lime' | 'green' |
+          'emerald' | 'teal' | 'cyan' | 'sky' | 'blue' | 'indigo' | 'violet' |
+          'purple' | 'fuchsia' | 'pink' | 'rose' | 'primary' | 'secondary' | 'tertiary';
+
+  /**
+   * Clases CSS adicionales para posicionamiento o personalización
+   *
+   * Útil para posicionar el badge como overlay usando absolute positioning.
+   *
+   * **Advertencia:** Evita sobrescribir tamaños, colores o formas core del badge.
+   * Usa solo para posicionamiento, márgenes o efectos adicionales.
+   *
+   * @example
+   * ```tsx
+   * // Como overlay en botón
+   * <button className="relative">
+   *   <BellIcon />
+   *   <Notification count={5} className="absolute -top-1 -right-1" />
+   * </button>
+   *
+   * // Con margen personalizado
+   * <Notification count={3} className="ml-2" />
+   *
+   * // Con sombra adicional
+   * <Notification count={7} className="shadow-lg" />
+   * ```
+   */
+  className?: string;
+
+  /**
+   * Label de accesibilidad (ARIA) personalizado
+   *
+   * Si no se proporciona, se genera automáticamente:
+   * - Con count: "{count} notificación(es)"
+   * - Sin count: "Notificación pendiente"
+   *
+   * **Mejores prácticas:**
+   * - Describe el tipo de notificación si es específico
+   * - Incluye contexto relevante para screen readers
+   * - Mantén el texto conciso pero descriptivo
+   *
+   * @example
+   * ```tsx
+   * // Auto-generado (recomendado)
+   * <Notification count={5} />
+   * // → aria-label="5 notificaciones"
+   *
+   * // Personalizado
+   * <Notification count={3} ariaLabel="3 mensajes no leídos" />
+   * <Notification ariaLabel="Nueva alerta de seguridad" />
+   * ```
+   *
+   * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html
+   */
+  ariaLabel?: string;
+}

package/src/components/Notification/README.md

@@ -0,0 +1,409 @@
+# Notification Badge
+
+Badge de notificación para mostrar alertas, mensajes o notificaciones pendientes. Puede mostrar un punto simple o un contador numérico con límite automático a 99+.
+
+## 🎯 Características
+
+- ✅ Soporte completo de dark mode
+- ✅ Dos variantes: badge simple (dot) o badge con número
+- ✅ Límite automático a 99+ para números grandes
+- ✅ 20+ colores personalizables
+- ✅ TypeScript con types estrictos
+- ✅ Accesibilidad con ARIA labels automáticos
+- ✅ Pixel-perfect según especificaciones de Figma
+- ✅ Ideal como overlay en iconos, botones o avatares
+
+## 📦 Instalación
+
+```tsx
+import { Notification } from './components/Notification';
+```
+
+## 🚀 Uso Básico
+
+### Badge Simple (Dot)
+```tsx
+// Punto rojo simple de 8px × 8px
+<Notification />
+
+// Con count=0 también muestra punto
+<Notification count={0} />
+```
+
+### Badge con Número
+```tsx
+// Badge con contador
+<Notification count={5} />
+
+// Límite automático a 99+
+<Notification count={150} />  // Muestra "99+"
+```
+
+### Badge con Color Personalizado
+```tsx
+<Notification count={3} color="red" />      // Error/Crítico (default)
+<Notification count={5} color="orange" />   // Advertencia
+<Notification count={8} color="green" />    // Éxito
+<Notification count={2} color="blue" />     // Info
+<Notification count={1} color="purple" />   // Especial
+```
+
+### Como Overlay en Botón
+```tsx
+<button className="relative p-3 bg-white border rounded-lg">
+  <BellIcon className="w-6 h-6" />
+  <Notification count={5} className="absolute -top-1 -right-1" />
+</button>
+```
+
+## 🎨 Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `count` | `number \| undefined` | `undefined` | Número de notificaciones. `undefined`/`0` = dot, `1-99` = número, `100+` = "99+" |
+| `color` | `'red' \| 'orange' \| 'yellow' \| 'green' \| 'blue' \| 'purple' \| 'zinc' \| ...` | `'red'` | Color del badge (20+ colores disponibles) |
+| `className` | `string` | `''` | Clases CSS adicionales para posicionamiento |
+| `ariaLabel` | `string` | Auto-generado | Label de accesibilidad (incluye conteo automático) |
+
+## 📏 Especificaciones
+
+### Badge Simple (Dot)
+- **Dimensiones**: 8px × 8px (w-2 h-2)
+- **Forma**: rounded-full (circular)
+- **Uso**: Indica notificaciones sin especificar cantidad
+
+### Badge con Número
+- **Altura**: 16px (h-4)
+- **Ancho mínimo**: 16px (min-w-[16px])
+- **Padding horizontal**: 4px (px-1)
+- **Tipografía**: 10px Bold, leading-none
+- **Forma**: rounded-full (pill)
+- **Límite**: Números ≥ 100 muestran "99+"
+
+## 🎨 Colores Disponibles
+
+El badge soporta 20+ colores para diferentes contextos:
+
+| Color | Uso Recomendado | Ejemplo |
+|-------|-----------------|---------|
+| `red` (default) | Errores, alertas críticas | `<Notification count={5} color="red" />` |
+| `orange` | Advertencias importantes | `<Notification count={3} color="orange" />` |
+| `yellow` | Avisos, atención requerida | `<Notification count={2} color="yellow" />` |
+| `green` | Confirmaciones, éxitos | `<Notification count={8} color="green" />` |
+| `blue` | Información general | `<Notification count={7} color="blue" />` |
+| `purple` | Especiales, premium | `<Notification count={1} color="purple" />` |
+| `zinc` | Notificaciones neutras | `<Notification count={4} color="zinc" />` |
+
+**Colores adicionales disponibles**: `amber`, `lime`, `emerald`, `teal`, `cyan`, `sky`, `indigo`, `violet`, `fuchsia`, `pink`, `rose`, `primary`, `secondary`, `tertiary`
+
+## 🎯 Casos de Uso
+
+### 1. Overlay en Botón de Navegación
+```tsx
+<nav className="flex items-center justify-between p-4">
+  <Logo />
+  <div className="flex items-center gap-4">
+    <button className="relative p-2 hover:bg-gray-100 rounded">
+      <BellIcon className="w-5 h-5" />
+      <Notification count={3} className="absolute -top-1 -right-1" />
+    </button>
+    <UserMenu />
+  </div>
+</nav>
+```
+
+### 2. Contador en Menú Lateral
+```tsx
+<aside className="w-64">
+  <MenuItem href="/dashboard">Dashboard</MenuItem>
+  <MenuItem href="/notifications">
+    Notificaciones
+    <Notification count={12} className="ml-auto" />
+  </MenuItem>
+  <MenuItem href="/messages">
+    Mensajes
+    <Notification count={5} className="ml-auto" />
+  </MenuItem>
+</aside>
+```
+
+### 3. Overlay en Avatar
+```tsx
+<div className="relative">
+  <img src="/avatar.jpg" className="w-12 h-12 rounded-full" />
+  <Notification count={3} className="absolute -top-1 -right-1" />
+</div>
+```
+
+### 4. Indicador de Estado en Lista
+```tsx
+<div className="space-y-2">
+  <div className="flex items-center gap-3 p-2">
+    <Notification color="red" />
+    <span>Urgente: Revisar servidor</span>
+  </div>
+  <div className="flex items-center gap-3 p-2">
+    <Notification color="orange" />
+    <span>Advertencia: Actualización disponible</span>
+  </div>
+  <div className="flex items-center gap-3 p-2">
+    <Notification color="blue" />
+    <span>Info: Nuevo feature disponible</span>
+  </div>
+</div>
+```
+
+### 5. Contador en Tabs
+```tsx
+<div className="flex border-b">
+  <button className="flex items-center gap-2 px-4 py-2 border-b-2 border-blue-600">
+    Pendientes
+    <Notification count={8} />
+  </button>
+  <button className="flex items-center gap-2 px-4 py-2">
+    En Progreso
+    <Notification count={3} color="blue" />
+  </button>
+  <button className="px-4 py-2">
+    Completados
+  </button>
+</div>
+```
+
+## 🌓 Dark Mode
+
+El componente se adapta automáticamente a dark mode:
+
+```tsx
+// Funciona automáticamente con la clase 'dark' en <html>
+<html className="dark">
+  <body>
+    <Notification count={5} />
+    {/* Badge mantiene visibilidad y contraste en dark mode */}
+  </body>
+</html>
+```
+
+**Adaptaciones en Dark Mode:**
+- Colores mantienen intensidad (ej: content-extensions-red #b91c1c)
+- Texto siempre blanco para máximo contraste
+- Sin bordes en badge simple para mantener limpieza visual
+
+## ♿ Accesibilidad
+
+### ARIA Labels Automáticos
+El componente genera automáticamente labels descriptivos:
+
+```tsx
+// Badge simple
+<Notification />
+// → aria-label="Notificación pendiente"
+
+// Badge con número
+<Notification count={5} />
+// → aria-label="5 notificaciones"
+
+<Notification count={1} />
+// → aria-label="1 notificación"
+```
+
+### ARIA Label Personalizado
+Proporciona un label específico cuando necesites más contexto:
+
+```tsx
+<Notification
+  count={5}
+  ariaLabel="5 mensajes no leídos de soporte"
+/>
+
+<Notification
+  ariaLabel="Nueva alerta de seguridad crítica"
+/>
+```
+
+### Role Status
+Todos los badges incluyen `role="status"` para anunciar cambios a lectores de pantalla.
+
+## 🎨 Tokens de Color Utilizados
+
+El componente usa **exclusivamente tokens del sistema de diseño**:
+
+### Light Mode
+- Badge red (default): `bg-content-extensions-red` (#b91c1c)
+- Otros colores: `bg-{color}-700` (ej: orange-700, green-700)
+- Texto: `text-white` (#ffffff)
+
+### Dark Mode
+- Colores mantienen intensidad: `dark:bg-content-extensions-red`, `dark:bg-{color}-700`
+- Texto: `dark:text-white` (#ffffff)
+
+### Token Extensions
+El token `content-extensions-red` está definido en `tailwind.config.js` y garantiza consistencia en todos los badges del sistema.
+
+## 💡 Mejores Prácticas
+
+### ✅ Hacer
+- Usa badge simple (sin count) cuando no necesites mostrar número exacto
+- Usa badge con número para mostrar cantidad de notificaciones pendientes
+- Posiciona como overlay usando `className="absolute -top-1 -right-1"` en elemento `relative`
+- Proporciona `ariaLabel` descriptivo cuando el contexto no sea obvio
+- Usa colores semánticos (red=error, orange=warning, green=success, blue=info)
+- Combina con botones, iconos o avatares para indicar estado
+
+### ❌ Evitar
+- No uses el badge como botón interactivo (es un indicador de estado)
+- No muestres números mayores a 99 sin usar el límite automático (ya incluido)
+- No uses como reemplazo de texto explicativo (es complementario)
+- No olvides envolver en `relative` cuando uses posicionamiento absoluto
+- No uses colores sin significado semántico consistente
+
+## 📐 Posicionamiento
+
+### Posicionamiento Absoluto (Overlay)
+Para usar como overlay sobre otro elemento:
+
+```tsx
+{/* Elemento padre debe tener position: relative */}
+<div className="relative">
+  <YourElement />
+  <Notification count={5} className="absolute -top-1 -right-1" />
+</div>
+```
+
+**Variantes de posición comunes:**
+- Esquina superior derecha: `-top-1 -right-1`
+- Esquina superior izquierda: `-top-1 -left-1`
+- Sin overflow: `top-0 right-0`
+- Con más separación: `-top-2 -right-2`
+
+### Posicionamiento Inline
+Para usar dentro del flujo normal:
+
+```tsx
+<div className="flex items-center gap-2">
+  <span>Notificaciones</span>
+  <Notification count={12} />
+</div>
+```
+
+## 🔗 Recursos Relacionados
+
+- **Figma**: [Notification Badge](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4310-22651&m=dev)
+- **Storybook**: Ejecuta `npm run storybook` y navega a "Siesa UI Kit/Notification"
+- **Documentación**:
+  - [Sistema de colores](../../../docs/colors.md)
+  - [Guía de dark mode](../../../docs/dark-mode-guide.md)
+  - [Tipografía](../../../docs/typography.md)
+
+## 📝 Ejemplo Completo
+
+```tsx
+import { useState } from 'react';
+import { Notification } from './components/Notification';
+
+function NotificationCenter() {
+  const [unreadCount, setUnreadCount] = useState(5);
+
+  const handleMarkAllRead = () => {
+    setUnreadCount(0);
+  };
+
+  return (
+    <nav className="flex items-center justify-between p-4 bg-white border-b">
+      <h1 className="text-lg font-bold">Mi App</h1>
+
+      <div className="flex items-center gap-4">
+        {/* Badge como overlay en botón */}
+        <button
+          className="relative p-2 hover:bg-gray-100 rounded transition-colors"
+          onClick={() => console.log('Ver notificaciones')}
+          aria-label={
+            unreadCount > 0
+              ? `${unreadCount} notificaciones no leídas`
+              : 'Notificaciones'
+          }
+        >
+          <BellIcon className="w-5 h-5" />
+          {unreadCount > 0 && (
+            <Notification
+              count={unreadCount}
+              className="absolute -top-1 -right-1"
+            />
+          )}
+        </button>
+
+        {/* Badge inline en menú */}
+        <div className="flex items-center gap-2 px-3 py-2 bg-blue-50 rounded">
+          <span className="text-sm">Mensajes</span>
+          <Notification count={3} color="blue" />
+        </div>
+
+        <button
+          onClick={handleMarkAllRead}
+          className="text-sm text-blue-600 hover:underline"
+        >
+          Marcar todo como leído
+        </button>
+      </div>
+    </nav>
+  );
+}
+```
+
+## 🐛 Solución de Problemas
+
+### El badge no se ve
+- Verifica que el componente esté renderizándose (inspecciona en DevTools)
+- Si usas posicionamiento absoluto, verifica que el padre tenga `relative`
+- Verifica que los colores de Tailwind estén cargados correctamente
+
+### El badge se solapa con otros elementos
+- Ajusta el offset usando `-top-2 -right-2` en lugar de `-top-1 -right-1`
+- Considera usar `z-10` o `z-20` en className si hay problemas de z-index
+
+### El número no se muestra
+- Verifica que `count` sea mayor a 0
+- Si `count={0}` o `count={undefined}`, se muestra badge simple (dot)
+
+### El color no se aplica
+- Verifica que el color esté en la lista de colores disponibles
+- Usa nombres en minúscula (ej: `"red"`, no `"Red"`)
+
+---
+
+## 📋 Historial de Cambios
+
+### v2.0.0 (2025-11-19) - Refactorización Mayor ⭐⭐⭐
+- 🚨 **BREAKING CHANGE**: Componente completamente refactorizado
+- ✅ **ELIMINADO**: Icono de campana - ahora es badge puro (sin botón)
+- ✅ **ELIMINADAS** props: `size`, `showBadge`, `onClick` (ya no es interactivo)
+- ✅ **RENOMBRADAS** props: `badgeCount` → `count`, `badgeColor` → `color`
+- ✅ **NUEVA API**: Componente ahora es `<span>` para uso como overlay o inline
+- ✅ **Simplificado**: De 7 props a 4 props (count, color, className, ariaLabel)
+- ✅ **Alineado con Figma**: Badge puro sin elementos adicionales
+- ✅ **Specs estandarizadas**:
+  - Badge simple: 8px × 8px fijo (w-2 h-2)
+  - Badge con número: 16px altura (h-4), min-w-[16px], 10px Bold
+- ✅ **ARIA label dinámico mejorado**: Genera automáticamente labels con singular/plural correcto
+- ✅ **Build validado**: Sin errores ni warnings
+- ✅ **Stories actualizadas**: 7 historias nuevas con ejemplos de overlay y uso real
+
+### v1.2.0 (2025-11-19)
+- ✅ Prop `badgeColor` con 20+ colores personalizables
+- ✅ Estandarización de tamaños de badges
+- ✅ ARIA label dinámico automático
+- ✅ Alineación con componente Button
+
+### v1.1.0 (2025-11-19)
+- ✅ Migración a tokens del sistema
+- ✅ Dark mode mejorado
+- ✅ Tipografía pixel-perfect
+
+### v1.0.0 (2025-11-11)
+- 🎉 Versión inicial
+
+---
+
+**Versión**: 2.0.0
+**Última actualización**: 2025-11-19
+**Autor**: Siesa UI Kit Team

package/{dist/components/Notification/index.d.ts → src/components/Notification/index.ts}

@@ -1,3 +1,3 @@
-export { Notification } from './Notification';
-export type { NotificationProps } from './Notification.types';
-//# sourceMappingURL=index.d.ts.map
+// index.ts
+export { Notification } from './Notification';
+export type { NotificationProps } from './Notification.types';