prometeo-design-system 1.0.0

package/README.md

@@ -0,0 +1,801 @@
+# Desing components
+
+## Button Component
+
+```tsx
+import Button from "./components/Button";
+import type {
+  ButtonVariant,
+  ButtonColor,
+  ButtonSize,
+  ButtonState,
+} from "./components/Button";
+```
+
+```tsx
+import Button from "./components/Button";
+
+function App() {
+  return (
+    <div>
+      {/* Botón básico */}
+      <Button label="Click me" onClick={() => console.log("Clicked!")} />
+
+      {/* Botón con icono */}
+      <Button
+        label="Guardar"
+        icon={<SaveIcon />}
+        variant="filled"
+        color="primary"
+      />
+
+      {/* Botón de carga */}
+      <Button
+        label="Enviando..."
+        isLoading={true}
+        Spinner={<CustomSpinner />}
+      />
+    </div>
+  );
+}
+```
+
+## 📋 API Reference
+
+### Props
+
+| Prop              | Tipo                              | Default     | Descripción                                     |
+| ----------------- | --------------------------------- | ----------- | ----------------------------------------------- |
+| `label`           | `string`                          | `undefined` | Texto a mostrar en el botón                     |
+| `onClick`         | `() => void`                      | `undefined` | Función ejecutada al hacer click                |
+| `icon`            | `React.ReactNode`                 | `undefined` | Icono a mostrar (se anima en hover)             |
+| `classButton`     | `string`                          | `undefined` | Clases CSS personalizadas para el botón         |
+| `classButtonText` | `string`                          | `undefined` | Clases CSS personalizadas para el texto         |
+| `animate`         | `boolean`                         | `true`      | Habilita/deshabilita animaciones del botón      |
+| `animateIcon`     | `boolean`                         | `true`      | Habilita/deshabilita animaciones del icono      |
+| `isLoading`       | `boolean`                         | `false`     | Muestra estado de carga                         |
+| `disabled`        | `boolean`                         | `false`     | Deshabilita el botón                            |
+| `type`            | `"button" \| "submit" \| "reset"` | `"button"`  | Tipo de botón HTML                              |
+| `variant`         | `ButtonVariant`                   | `"filled"`  | Estilo visual del botón                         |
+| `color`           | `ButtonColor`                     | `"primary"` | Esquema de colores                              |
+| `size`            | `ButtonSize`                      | `"medium"`  | Tamaño del botón                                |
+| `children`        | `React.ReactNode`                 | `undefined` | Contenido personalizado (anula label e icon)    |
+| `Spinner`         | `React.ReactNode`                 | `undefined` | Spinner personalizado para estado loading       |
+| `forceState`      | `ButtonState`                     | `undefined` | Fuerza un estado específico (útil para testing) |
+
+### Tipos Exportados
+
+```tsx
+type ButtonVariant = "filled" | "outline" | "text";
+type ButtonColor = "primary" | "secondary";
+type ButtonSize = "small" | "medium" | "large";
+type ButtonState = "enabled" | "hovered" | "focused" | "pressed" | "disabled";
+```
+
+## Variantes
+
+### Filled (Default)
+
+Botones con fondo sólido, ideales para acciones primarias.
+
+```tsx
+<Button variant="filled" color="primary" label="Primary Filled" />
+<Button variant="filled" color="secondary" label="Secondary Filled" />
+```
+
+### Outline
+
+Botones con bordes y fondo transparente, ideales para acciones secundarias.
+
+```tsx
+<Button variant="outline" color="primary" label="Primary Outline" />
+```
+
+### Text
+
+Botones solo con texto, ideales para acciones terciarias o enlaces.
+
+```tsx
+<Button variant="text" color="primary" label="Primary Text" />
+<Button variant="text" color="secondary" label="Secondary Text" />
+```
+
+## Colores
+
+### Primary
+
+Color principal usado para acciones importantes.
+
+```tsx
+<Button color="primary" label="Primary Action" />
+```
+
+### Secondary
+
+Color secundario usado para acciones menos importantes.
+
+```tsx
+<Button color="secondary" label="Secondary Action" />
+```
+
+## Tamaños
+
+### Small (40px)
+
+```tsx
+<Button size="small" label="Small Button" />
+// Dimensiones: h-[40px] min-w-[123px] px-2 text-sm
+```
+
+### Medium (48px) - Default
+
+```tsx
+<Button size="medium" label="Medium Button" />
+// Dimensiones: h-[48px] min-w-[134px] px-2 text-base
+```
+
+### Large (56px)
+
+```tsx
+<Button size="large" label="Large Button" />
+// Dimensiones: h-[56px] min-w-[145px] px-4 py-3 text-base
+```
+
+## ⚡ Animaciones
+
+El componente incluye varias animaciones por defecto:
+
+### Animaciones del Botón
+
+- **Hover**: Escala a 1.05x
+- **Tap**: Escala a 0.98x
+- **Transición**: Spring animation con stiffness: 400, damping: 17
+
+### Animaciones del Icono
+
+- **Hover**: Rotación de 90 grados (si `animateIcon` está habilitado)
+- **Transición**: Spring animation suave
+
+```tsx
+{
+  /* Deshabilitar todas las animaciones */
+}
+<Button animate={false} animateIcon={false} />;
+
+{
+  /* Solo deshabilitar animación del icono */
+}
+<Button animateIcon={false} icon={<Icon />} label="Icono estático" />;
+```
+
+## 🔄 Estado de Carga
+
+```tsx
+const [loading, setLoading] = useState(false);
+
+const handleSubmit = async () => {
+  setLoading(true);
+  try {
+    await submitForm();
+  } finally {
+    setLoading(false);
+  }
+};
+
+return (
+  <Button
+    label="Enviar Formulario"
+    isLoading={loading}
+    onClick={handleSubmit}
+    Spinner={<CustomSpinner />} // Spinner personalizado
+  />
+);
+```
+
+**Comportamiento del Loading:**
+
+- Muestra un spinner (personalizable)
+- En tamaño `small` solo muestra el spinner
+- En tamaños `medium` y `large` muestra spinner + texto "Cargando..."
+- Deshabilita automáticamente el botón
+- Detiene todas las animaciones
+
+### Clases Personalizadas
+
+```tsx
+<Button
+  classButton="bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600"
+  classButtonText="font-bold text-lg"
+  label="Botón Gradient"
+/>
+```
+
+### Contenido Personalizado Ejemplo
+
+```tsx
+<Button onClick={handleClick}>
+  <div className="flex items-center gap-3">
+    <Avatar src="/user.jpg" size="sm" />
+    <div className="text-left">
+      <p className="font-semibold">John Doe</p>
+      <p className="text-xs opacity-70">Desarrollador</p>
+    </div>
+    <ChevronDownIcon className="w-4 h-4" />
+  </div>
+</Button>
+```
+
+## Uso Comunes
+
+### Botón de Envío de Formulario
+
+```tsx
+<Button
+  type="submit"
+  variant="filled"
+  color="primary"
+  size="medium"
+  label="Enviar"
+  isLoading={isSubmitting}
+  disabled={!isFormValid}
+/>
+```
+
+### Botón de Acción con Icono
+
+```tsx
+<Button
+  label="Descargar PDF"
+  icon={<DownloadIcon />}
+  variant="outline"
+  onClick={downloadPDF}
+/>
+```
+
+### Botón de Cancelar
+
+```tsx
+<Button label="Cancelar" variant="text" color="secondary" onClick={onCancel} />
+```
+
+### Botón de Eliminar
+
+```tsx
+<Button
+  label="Eliminar"
+  variant="outline"
+  color="primary"
+  icon={<TrashIcon />}
+  classButton="border-red-500 text-red-500 hover:bg-red-50"
+  onClick={handleDelete}
+/>
+```
+
+## Sistema de Colores (Design Tokens)
+
+El componente utiliza un sistema de design tokens de Tailwind CSS. Los colores se mapean así:
+
+### Primary Colors
+
+```css
+/* Filled Primary */
+bg-primary-default-default
+text-neutral-strong-default
+hover:bg-primary-default-hover
+
+/* Outline Primary */
+border-primary-medium-default
+text-primary-medium-default
+hover:border-primary-medium-hover
+```
+
+### Secondary Colors
+
+```css
+/* Filled Secondary */
+bg-neutral-strong-medium-default
+text-neutral-strong-default
+
+/* Text Secondary */
+text-neutral-strong-default
+hover:text-primary-default-hover
+```
+
+---
+
+### Sidebar Component
+
+Un componente de barra lateral completo y altamente funcional con soporte para navegación, perfil de usuario, gestión de sesiones múltiples, notificaciones y estados colapsables. Diseñado para aplicaciones empresariales con múltiples usuarios y funcionalidades avanzadas.
+
+## 🚀 Características Principales
+
+- ✅ **Navegación colapsable** con animaciones suaves
+- ✅ **Perfil de usuario** con gestión de sesiones múltiples
+- ✅ **Sistema de notificaciones** con badge
+- ✅ **Logo de empresa** dinámico
+- ✅ **Enlaces de navegación** categorizados (páginas y utilidades)
+- ✅ **Menú contextual** para usuarios en modo colapsado
+- ✅ **Detección de clicks externos** para cerrar menús
+- ✅ **Estados activos** para navegación actual
+- ✅ **Responsive** y accesible
+
+## 📦 Dependencias
+
+```bash
+npm install react-router-dom framer-motion
+# o
+yarn add react-router-dom framer-motion
+```
+
+## 📋 Importaciones Requeridas
+
+```tsx
+import type { SessionLocalStorage } from "@/interfaces/User/SessionLocalStorage";
+import type { IUser } from "shared-dependencies-tickets";
+import Menu from "../Menu/Menu";
+import { Badge } from "./components/badge";
+import { NavbarCollapseButton } from "./components/collapse-button";
+import { CompanyLogo } from "./components/company-logo";
+import { NavbarLinks } from "./components/nav-links";
+import { UserProfile } from "./components/user-profile";
+import { useNavbarCollapse } from "./hooks/useNavBarCollapse";
+import { useNavbarLinks, type INavLink } from "./hooks/useNavLinks";
+import { useNavbarAnimations } from "./ui/useNavbarAnimation";
+```
+
+## 🎯 Uso Básico
+
+```tsx
+import Sidebar from "./components/Sidebar";
+
+function App() {
+  const user = {
+    id: 1,
+    name: "Juan Pérez",
+    email: "juan@empresa.com",
+    company_id: {
+      name: "Mi Empresa",
+      logo: "/logo-empresa.png",
+    },
+  };
+
+  const sessions = [
+    { token: "token1", user_id: 1, email: "juan@empresa.com" },
+    { token: "token2", user_id: 2, email: "maria@empresa.com" },
+  ];
+
+  const links = {
+    pages: [
+      {
+        id: "dashboard",
+        label: "Dashboard",
+        path: "/dashboard",
+        icon: <DashboardIcon />,
+      },
+      {
+        id: "projects",
+        label: "Proyectos",
+        path: "/projects",
+        icon: <ProjectIcon />,
+      },
+    ],
+    utils: [
+      {
+        id: "notifications",
+        label: "Notificaciones",
+        path: "/notifications",
+        icon: <BellIcon />,
+      },
+    ],
+  };
+
+  return (
+    <div className="flex h-screen">
+      <Sidebar
+        user={user}
+        sessions={sessions}
+        handleLogout={(user) => console.log("Logout", user)}
+        handleTokenLogin={(token) => console.log("Switch user", token)}
+        links={links}
+        isActiveModalNotification={false}
+        setIsActiveModalNotification={() => {}}
+        handleNotificationClick={() => console.log("Notifications")}
+        handleProfileClick={() => console.log("Profile")}
+      />
+      <main className="flex-1">{/* Contenido principal */}</main>
+    </div>
+  );
+}
+```
+
+## 📋 API Reference
+
+### Props Principales
+
+| Prop                           | Tipo                                     | Requerido | Descripción                                                 |
+| ------------------------------ | ---------------------------------------- | --------- | ----------------------------------------------------------- |
+| `user`                         | `IUser`                                  | ✅        | Información del usuario actual                              |
+| `sessions`                     | `SessionLocalStorage[]`                  | ✅        | Lista de sesiones activas disponibles                       |
+| `handleLogout`                 | `(user: IUser) => void`                  | ✅        | Función para cerrar sesión                                  |
+| `handleTokenLogin`             | `(token: string) => void`                | ✅        | Función para cambiar entre sesiones                         |
+| `links`                        | `Record<"pages" \| "utils", INavLink[]>` | ✅        | Enlaces de navegación categorizados                         |
+| `isActiveModalNotification`    | `boolean`                                | ✅        | Estado del modal de notificaciones                          |
+| `setIsActiveModalNotification` | `(state: boolean) => void`               | ✅        | Función para controlar modal de notificaciones              |
+| `handleNotificationClick`      | `() => void`                             | ✅        | Función ejecutada al hacer click en notificaciones          |
+| `handleProfileClick`           | `() => void`                             | ❌        | Función ejecutada al hacer click en perfil (modo expandido) |
+
+### Tipos de Datos
+
+```tsx
+interface IUser {
+  id: number;
+  name: string;
+  email: string;
+  company_id: {
+    name: string;
+    logo: string;
+  };
+  // ... otros campos del usuario
+}
+
+interface SessionLocalStorage {
+  token: string;
+  user_id: number;
+  email: string;
+  // ... otros campos de sesión
+}
+
+interface INavLink {
+  id: string;
+  label: string;
+  path: string;
+  icon: React.ReactNode;
+  badge?: number; // Para mostrar contadores
+  disabled?: boolean;
+}
+```
+
+## 🏗️ Estructura del Componente
+
+### Layout Principal
+
+```
+┌─────────────────────────┐
+│ [Collapse Button]       │
+├─────────────────────────┤
+│ [Company Logo]          │
+├─────────────────────────┤
+│ ─────────────────       │ ← Separador
+├─────────────────────────┤
+│                         │
+│ [Navigation Links]      │
+│ • Dashboard             │
+│ • Proyectos             │
+│ • Reportes              │
+│                         │
+├─────────────────────────┤ ← Flex Grow
+│                         │
+│ [Utility Links]         │
+│ • Notificaciones [2]    │
+│ • Configuración         │
+│                         │
+├─────────────────────────┤
+│ ─────────────────       │ ← Separador
+├─────────────────────────┤
+│ [User Profile]          │
+│ • Avatar + Nombre       │
+│ • Sesiones múltiples    │
+└─────────────────────────┘
+```
+
+### Estados del Sidebar
+
+#### 1. **Expandido** (w-64 / 256px)
+
+- Muestra todos los elementos con texto
+- Logo completo de la empresa
+- Enlaces con iconos y etiquetas
+- Perfil de usuario completo
+
+#### 2. **Colapsado** (w-16 / 64px)
+
+- Solo muestra iconos
+- Logo reducido
+- Enlaces solo con iconos
+- Avatar de usuario solamente
+
+#### 3. **Colapsado + Menú Contextual**
+
+- Sidebar colapsado
+- Menú flotante con opciones de usuario
+- Cambio de sesiones disponible
+
+## 🎨 Componentes Internos
+
+### NavbarCollapseButton
+
+Botón para alternar entre estado expandido y colapsado.
+
+```tsx
+<NavbarCollapseButton isCollapsed={isCollapsed} onToggle={toggleCollapse} />
+```
+
+### CompanyLogo
+
+Muestra el logo y nombre de la empresa del usuario.
+
+```tsx
+<CompanyLogo
+  logoUrl={user?.company_id.logo || ""}
+  companyName={user?.company_id.name}
+/>
+```
+
+
+
+```tsx
+
+<NavbarLinks
+  links={pageLinks}
+  isLinkActive={isLinkActive}
+/>
+
+
+<NavbarLinks
+  links={utilLinks}
+  componentBadge={() => <Badge notificationsCount={0} />}
+  onClick={handleNotificationClick}
+  isLinkActive={isLinkActive}
+  activeModal={isActiveModalNotification}
+/>
+```
+
+### UserProfile
+
+Perfil de usuario con gestión de sesiones múltiples.
+
+```tsx
+<UserProfile
+  sessions={sessions}
+  user={user}
+  isExpanded={isExpanded}
+  showOptions={true}
+  onProfileClick={handleProfileClick}
+  onClick={toggleExpandedUserConfig}
+  onClickLogout={handleLogout}
+  handleTokenLogin={handleTokenLogin}
+/>
+```
+
+
+
+##  Estados
+
+### Estados Internos
+
+```tsx
+const [isCollapsed, setIsCollapsed] = useState(false); // Sidebar colapsado
+const [isExpanded, setIsExpanded] = useState(false); // Menú de usuario expandido
+const [isExpandedUserConfig, setIsExpandedUserConfig] = useState(false); // Config de usuario
+```
+
+### Comportamientos Automáticos
+
+1. **Click fuera del menú**: Cierra automáticamente el menú de configuración de usuario
+2. **Colapsar sidebar**: Automáticamente cierra los menús expandidos
+3. **Cambio de sesión**: Cierra el menú de usuario tras cambiar sesión
+
+### Lógica de Interacciones
+
+```tsx
+// Alternar colapso del sidebar
+const toggleCollapse = () => {
+  setIsExpandedUserConfig(false); // Cierra menú de usuario
+  setIsCollapsed(!isCollapsed);
+};
+
+// Manejar click en perfil (diferentes comportamientos según estado)
+const handleLocalProfileClick = () => {
+  setIsExpandedUserConfig(!isExpandedUserConfig);
+};
+
+// Click externo para cerrar menú
+useEffect(() => {
+  const handleClickOutside = (event: MouseEvent) => {
+    if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
+      setIsExpandedUserConfig(false);
+    }
+  };
+
+  if (isExpandedUserConfig) {
+    document.addEventListener("mousedown", handleClickOutside);
+  }
+
+  return () => document.removeEventListener("mousedown", handleClickOutside);
+}, [isExpandedUserConfig]);
+```
+
+### Clases CSS Base
+
+```tsx
+className={`
+  bg-neutral-default-default
+  overflow-hidden
+  h-full
+  flex
+  flex-col
+  border-r
+  border-neutral-strong-default
+  transition-all
+  duration-300
+  ${isCollapsed ? 'w-16' : 'w-64'}
+`}
+```
+
+### Badges
+
+```tsx
+const CustomBadge = ({ count }: { count: number }) => (
+  <div className="bg-red-500 text-white rounded-full w-5 h-5 flex items-center justify-center text-xs">
+    {count > 99 ? "99+" : count}
+  </div>
+);
+
+<NavbarLinks
+  links={utilLinks}
+  componentBadge={() => <CustomBadge count={notificationCount} />}
+  // ... otras props
+/>;
+```
+
+### Enlaces Dinámicos por Rol
+
+```tsx
+const getLinksForUser = (user: IUser) => {
+  const baseLinks = [
+    {
+      id: "dashboard",
+      label: "Dashboard",
+      path: "/dashboard",
+      icon: <HomeIcon />,
+    },
+  ];
+
+  if (user.role === "admin") {
+    baseLinks.push(
+      { id: "users", label: "Usuarios", path: "/users", icon: <UsersIcon /> },
+      {
+        id: "settings",
+        label: "Configuración",
+        path: "/settings",
+        icon: <SettingsIcon />,
+      }
+    );
+  }
+
+  return { pages: baseLinks, utils: [] };
+};
+```
+
+
+
+##  Ejemplo de uso
+
+### Navbar completo
+
+```tsx
+import { useState, useEffect } from "react";
+import { useNavigate, useLocation } from "react-router-dom";
+import Sidebar from "./components/Sidebar";
+
+function Navbar() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [user, setUser] = useState(null);
+  const [sessions, setSessions] = useState([]);
+  const [notificationCount, setNotificationCount] = useState(0);
+  const [showNotifications, setShowNotifications] = useState(false);
+
+  const links = {
+    pages: [
+      {
+        id: "dashboard",
+        label: "Dashboard",
+        path: "/dashboard",
+        icon: <HomeIcon className="w-5 h-5" />,
+      },
+      {
+        id: "tickets",
+        label: "Tickets",
+        path: "/tickets",
+        icon: <TicketIcon className="w-5 h-5" />,
+      },
+      {
+        id: "projects",
+        label: "Proyectos",
+        path: "/projects",
+        icon: <FolderIcon className="w-5 h-5" />,
+      },
+      {
+        id: "reports",
+        label: "Reportes",
+        path: "/reports",
+        icon: <ChartIcon className="w-5 h-5" />,
+      },
+    ],
+    utils: [
+      {
+        id: "notifications",
+        label: "Notificaciones",
+        path: "/notifications",
+        icon: <BellIcon className="w-5 h-5" />,
+        badge: notificationCount,
+      },
+      {
+        id: "settings",
+        label: "Configuración",
+        path: "/settings",
+        icon: <SettingsIcon className="w-5 h-5" />,
+      },
+    ],
+  };
+
+  const handleLogout = async (user) => {
+    try {
+      await logoutUser(user);
+      navigate("/login");
+    } catch (error) {
+      console.error("Error al cerrar sesión:", error);
+    }
+  };
+
+  const handleTokenLogin = async (token) => {
+    try {
+      const newUser = await switchUserSession(token);
+      setUser(newUser);
+      navigate("/dashboard");
+    } catch (error) {
+      console.error("Error al cambiar sesión:", error);
+    }
+  };
+
+  const handleNotificationClick = () => {
+    setShowNotifications(true);
+    setNotificationCount(0);
+  };
+
+  return (
+    <div className="flex h-screen bg-gray-50">
+      <Sidebar
+        user={user}
+        sessions={sessions}
+        handleLogout={handleLogout}
+        handleTokenLogin={handleTokenLogin}
+        links={links}
+        isActiveModalNotification={showNotifications}
+        setIsActiveModalNotification={setShowNotifications}
+        handleNotificationClick={handleNotificationClick}
+        handleProfileClick={() => navigate("/profile")}
+      />
+    </div>
+  );
+}
+
+export default Navbar;
+
+
+//<!--- En otro lugar de nuestra app>
+
+ /* REACT ROUTER */
+      <main className="flex-1 overflow-auto p-6">
+        <Routes>
+          <Route path="/dashboard" element={<DashboardContent />} />
+          <Route path="/tickets" element={<TicketsContent />} />
+          <Route path="/projects" element={<ProjectsContent />} />
+          <Route path="/reports" element={<ReportsContent />} />
+          <Route path="/notifications" element={<NotificationsContent />} />
+          <Route path="/settings" element={<SettingsContent />} />
+          <Route path="/profile" element={<ProfileContent />} />
+        </Routes>
+      </main>
+```