@conatel-sa/react-ui

Biblioteca de componentes de interfaz para aplicaciones web hechas con React para productos Conatel y Vivion. Incluye botones, formularios, tablas, modales, tarjetas y más, con dos estilos visuales (temas) que se puede cambiar con una sola propiedad.

¿Para qué sirve? Para reutilizar pantallas y patrones de interfaz ya definidos: misma apariencia, menos trabajo de diseño pixel a pixel y menos CSS “a mano”. Sirve tanto para prototipos como para productos que quieran verse uniformes y cuidados en tipografía, colores y espaciados.

Qué necesitás antes de empezar

| Requisito | Notas | |-----------|--------| | Node.js (versión LTS recomendada) | Para ejecutar npm y crear el proyecto. nodejs.org | | Un proyecto React | Por ejemplo creado con Vite (npm create vite@latest → plantilla React + TypeScript). | | Conexión a internet (instalación típica) | Para descargar el paquete desde el registro npm (ver más abajo si usás archivo .tgz). |

Podés partir de los ejemplos de este documento y adaptarlos a tu pantalla.

Instalación

En la carpeta de tu proyecto React:

npm install @conatel-sa/react-ui

Instalar desde un archivo .tgz (sin usar el registro en el momento)

Útil si trabajás sin red en el entorno del proyecto, o si querés fijar exactamente un paquete que ya descargaste.

1. Obtener el archivo .tgz

• Con npm (recomendado): en una carpeta vacía o temporal, con internet:

  npm pack @conatel-sa/react-ui

  Eso genera un archivo conatel-sa-react-ui-<versión>.tgz en esa carpeta (el nombre incluye la versión publicada). Ese es el paquete listo para instalar offline.

• Desde la web: en la página del paquete en npm podés revisar la versión actual y, si hace falta, usar el mismo comando npm pack arriba para bajar el tarball correspondiente.

2. Instalarlo en tu proyecto React

Ajustá la ruta al .tgz que tengas (por ejemplo lo copiaste al repo en ./releases/):

npm install ./ruta/al/archivo/conatel-sa-react-ui-0.2.8.tgz

O en package.json:

"dependencies": {
  "@conatel-sa/react-ui": "file:./releases/conatel-sa-react-ui-0.2.8.tgz"
}

Luego: npm install.

Nota: si no podés ejecutar npm pack ni acceder al registro npm, podés pedir el .tgz a quien distribuya el material del desafío o al equipo, e instalarlo con los mismos pasos del punto 2.

Uso en 3 pasos

1. Importar los estilos (obligatorio)

Sin este archivo, los componentes no se verán con los colores y tipografías correctos. Ponelo una vez en el archivo de entrada de tu app (por ejemplo main.tsx o main.jsx):

import '@conatel-sa/react-ui/dist/index.css';

2. Envolver la app con el tema

Los componentes deben estar dentro de ThemeProvider. Elegís el tema visual con la prop theme:

import { ThemeProvider } from '@conatel-sa/react-ui';

function App() {
  return (
    <ThemeProvider theme="conatel" as="div">
      {/* Aquí van tus pantallas y componentes */}
    </ThemeProvider>
  );
}

• theme="conatel" — estilo con acento rojo corporativo.
• theme="vivion" — estilo con acento azul.

3. Usar componentes

import { ThemeProvider, Button, Card, CardBody, Badge } from '@conatel-sa/react-ui';

function Ejemplo() {
  return (
    <ThemeProvider theme="conatel" as="div">
      <Card>
        <CardBody>
          <Badge variant="success">Listo</Badge>
          <Button variant="primary">Continuar</Button>
        </CardBody>
      </Card>
    </ThemeProvider>
  );
}

Shell de autenticación (login / registro)

Tras importar dist/index.css, tenés clases listas para pantallas partidas (marca + formulario), pensadas para apps que adoptan los temas Conatel o Vivion:

| Clase | Uso | |--------|-----| | .login-split-container | Contenedor flex a pantalla completa | | .login-brand-side / .login-form-side | Columna izquierda (marca) y derecha (formulario) | | .auth-split--brand-end | Modificador: formulario a la izquierda, marca compacta a la derecha | | .login-title | Título con acento --color-primary del tema | | .login-split-container .btn-primary | CTA con degradé, hover y estado deshabilitado “sin apagar” (carga) | | .auth-text-link, .login-remember-label | Enlaces y label “recordarme” en gris co-marca | | .feature-icon | Iconos de bullets en el panel marca (sombra suave, sin borde) |

Requisitos: el árbol debe estar bajo ThemeProvider (theme-conatel o theme-vivion) para que existan --color-primary, --color-primary-hover y --color-primary-alpha. El bloque se concatena desde src/styles/app-chrome.css al publicar dist/index.css (ver tools/append-app-chrome.mjs en el repo de la librería).

Panel configuración (outline / eliminar)

| Clase | Uso | |--------|-----| | .settings-outline-btn (+ modificadores --compact, --icon, --h50, --h42, --toolbar, --accent-text) | Botón con borde neutro; hover/foco con box-shadow usando --color-primary-alpha (misma idea que button.form-select:focus) | | .settings-delete-outline-btn + .settings-delete-outline-btn__icon | Ícono en --color-danger; al hover/foco el ícono pasa a --color-accent-primary (rojo Conatel / celeste Vivion) | | .settings-segment-btn | Botones de segmento (ej. pestañas) con el mismo anillo al hover | | .settings-focus-ring | Solo refuerza el anillo en controles que ya definen borde |

Temas (resumen)

| Valor en código | Color principal aproximado | Uso típico | |-----------------|----------------------------|------------| | conatel | Rojo #CC032E | Identidad corporativa Conatel | | vivion | Azul #0098D4 | Identidad Vivion |

<ThemeProvider theme="vivion" as="div">
  <Button variant="primary">Acción principal</Button>
</ThemeProvider>

Si usás un asistente de código (opcional)

Texto de referencia que podés pegar para alinear criterios (no es obligatorio):

Estoy usando React y la librería @conatel-sa/react-ui. Importá ThemeProvider y los componentes que necesites desde @conatel-sa/react-ui. Preferí los componentes de la librería para botones e inputs en lugar de CSS global suelto. Importá @conatel-sa/react-ui/dist/index.css en el entry point.

Qué incluye el paquete principal

Import: import { … } from '@conatel-sa/react-ui'

| Área | Componentes (ejemplos) | |------|-------------------------| | Tipografía | Heading, Text | | Formularios | Input, Textarea, Select, Checkbox, Toggle, FormField | | Feedback | Badge, Alert, Spinner, Progress | | Contenedores | Card, CardHeader, CardBody, CardFooter, Modal | | Navegación | Navbar, NavItem, Tabs, TabList, Tab, TabPanel | | Datos | Table, TableHead, TableBody, TableRow, TableCell, TableHeaderCell | | Otros | Avatar, Divider, EmptyState, Button, Sidebar, SidebarItem, Toast, ScoreSelector |

Módulos opcionales (subrutas)

Además del paquete principal, podés importar solo lo que necesites desde rutas extra. Cada una tiene su documentación en tipos (.d.ts) dentro de node_modules/@conatel-sa/react-ui/dist/.

| Import | Para qué sirve | |--------|----------------| | @conatel-sa/react-ui/icons | Iconos Material Symbols y IconProvider. Suele hacer falta también: import '@conatel-sa/react-ui/dist/material-symbols.css' | | @conatel-sa/react-ui/forms | Campos avanzados: EmailInput, PasswordInput, MultiSelectDropdown, SingleSelectDropdown y utilidades de validación de contraseña | | @conatel-sa/react-ui/cards | Tarjetas y paneles: ServiceCard, FeatureCard, ChangelogPanel, ArtifactReportCard | | @conatel-sa/react-ui/dialogs | Diálogos (p. ej. ChangelogDialog; requiere react-dom) | | @conatel-sa/react-ui/metrics | StatInline, MiniMeter | | @conatel-sa/react-ui/status | StatusSummaryPopover |

Ejemplo: iconos

import { Icon, IconProvider } from '@conatel-sa/react-ui/icons';
import '@conatel-sa/react-ui/dist/material-symbols.css';

function ConIconos() {
  return (
    <ThemeProvider theme="conatel" as="div">
      <IconProvider injectStylesheet defaultSize="md">
        <Icon name="search" size="md" />
      </IconProvider>
    </ThemeProvider>
  );
}

lucide-react es opcional (solo si usás LucideIcon).

Ejemplo: formularios extendidos

import { EmailInput, PasswordInput } from '@conatel-sa/react-ui/forms';
import '@conatel-sa/react-ui/dist/index.css';
import '@conatel-sa/react-ui/dist/material-symbols.css';

Si algo no se ve bien (checklist rápido)

1. ¿Importaste import '@conatel-sa/react-ui/dist/index.css' en el entry (p. ej. main.tsx)?
2. ¿Tu contenido está dentro de <ThemeProvider>?
3. Si usás iconos o ./forms con símbolos, ¿importaste también material-symbols.css?
4. ¿Tu proyecto usa React 18? (peer dependency del paquete.)

TypeScript

La librería publica tipos (.d.ts). No necesitás instalar @types aparte para este paquete.

Más ayuda

• Página del paquete en npm: npmjs.com/package/@conatel-sa/react-ui
• Si tu equipo mantiene un repositorio workspace con este código, ahí suelen estar docs/ (subpaquetes, API de iconos y forms) y galerías HTML de demostración.