prometeo-design-system 1.3.0 → 1.3.2

package/README.md

@@ -1,796 +0,0 @@
-# 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
-```
-
-#### nota: No es necesario instalarlo, seguramente en el template del proyecto ya este instalado.
-
-## 📋 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>;
-```