UI Components (packages/ui/src/components)

Este directorio contiene los componentes visuales base (primitivos) de nuestra plataforma. Todo el sistema de diseño está construido sobre Radix UI y estilizado con Tailwind CSS v4 a través de la arquitectura de shadcn/ui.

El objetivo de esta carpeta es centralizar la "piel" de la aplicación, garantizando consistencia visual, accesibilidad (WAI-ARIA) y facilidad de mantenimiento.

Arquitectura y Principios

Para mantener el ecosistema escalable y predecible, todos los componentes dentro de src/components/base, src/components/shared, src/components/landing y src/components/dashboard-nidus deben cumplir las siguientes reglas:

1. Componentes presentacionales:

   • Los componentes aquí son puramente presentacionales.
   • No deben hacer fetching de datos.
   • No deben conectarse directamente a servicios externos (como Firebase).
   • Toda la lógica de negocio, manejo de estado complejo o validaciones (Zod) debe pasarse a través de props o delegarse a la app consumidora.

2. Estilizado Exclusivo con Tailwind v4:

   • Se utiliza Tailwind CSS para todo.
   • Prohibido el uso de estilos en línea (style={{...}}) salvo casos dinámicos extremos.
   • Utiliza las variables y tokens de diseño definidos en el tema principal de Tailwind. No uses colores o valores hardcodeados.

3. Iconografía:

   • Usar @repo/icons, que centraliza Lucide y Font Awesome.

4. Mobile First:

   • Todo componente debe ser responsivo por defecto, maquetando primero para pantallas móviles y aplicando modificadores (md:, lg:) progresivamente.

Cómo Utilizar los Componentes

Importar desde @repo/ui en apps. Los componentes están organizados en base, shared, landing y dashboard-nidus; el barrel src/index.ts también expone hooks, fonts, types y utils.

// Ejemplo de uso en un formulario o vista
import { Button, Input } from '@repo/ui';
import { Mail } from '@repo/icons';

export default function LoginForm() {
  return (
    <div className="flex flex-col gap-4">
      <Input type="email" placeholder="Correo electrónico" />
      <Button variant="default">
        <Mail className="mr-2 h-4 w-4" />
        Ingresar
      </Button>
    </div>
  );
}

Tooltips informativos de secciones

Para agregar una explicación contextual junto al título de una sección, usa exclusivamente FieldTooltip desde @repo/ui. No uses Tooltip, TooltipContent, atributos title ni otro componente de tooltip para este caso.

En cada módulo que necesite este tipo de ayuda, crea apps/<app>/modules/<module>/constants/tooltip.ts; si constants/ no existe, créala. El archivo debe exportar un objeto con los textos de las secciones, con nombre y claves en inglés, y as const. Mantén el copy fuera del JSX y en el idioma de la app:

// apps/system/modules/users/constants/tooltip.ts
export const USERS_SECTION_TOOLTIPS = {
  PROFILE: 'Información general de la persona y sus datos de contacto.',
  ACCESS: 'Roles y permisos disponibles para esta persona.',
} as const;

Importa el objeto desde el módulo y el componente desde la API pública @repo/ui:

import { FieldTooltip } from '@repo/ui';
import { USERS_SECTION_TOOLTIPS } from '../constants/tooltip';

<div className="flex items-center gap-2">
  <h2>Perfil</h2>
  <FieldTooltip text={USERS_SECTION_TOOLTIPS.PROFILE} />
</div>;

Esta regla aplica a tooltips informativos de secciones en módulos de apps. Los tooltips especializados de navegación colapsada, visualizaciones de datos y la página de demostración del primitive conservan su implementación específica.

Notification Drawer

NotificationDrawer está disponible desde @repo/ui y reemplaza el popover de notificaciones de la navbar. Recibe NotificationDrawerItem[] mediante notifications, expone callbacks para seleccionar una notificación o marcar todas como leídas, y usa Sheet responsive: ancho completo en mobile y un panel derecho de hasta 420px desde tablet.