@conatel-sa/react-ui 0.2.5 → 0.2.6

package/README.md

@@ -1,88 +1,180 @@
 # @conatel-sa/react-ui
 
-Biblioteca de componentes React para productos **Conatel** y **Vivion**. Más de 20 componentes UI listos para usar, con soporte de theming por marca mediante CSS custom properties. Export opcional de iconos (`./icons`).
+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](https://nodejs.org/) |
+| **Un proyecto React** | Por ejemplo creado con [Vite](https://vitejs.dev/) (`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:
+
 ```bash
 npm install @conatel-sa/react-ui
 ```
 
-## Uso rápido
+### 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:
+
+  ```bash
+  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/`):
+
+```bash
+npm install ./ruta/al/archivo/conatel-sa-react-ui-0.2.6.tgz
+```
+
+O en `package.json`:
+
+```json
+"dependencies": {
+  "@conatel-sa/react-ui": "file:./releases/conatel-sa-react-ui-0.2.6.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.
+
+---
 
-Importá el CSS de tokens **una sola vez** en el entry point de tu aplicación:
+## 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`):
 
 ```tsx
-// main.tsx
 import '@conatel-sa/react-ui/dist/index.css';
 ```
 
-Luego usá los componentes envueltos en un `ThemeProvider`:
+### 2. Envolver la app con el tema
+
+Los componentes deben estar **dentro** de `ThemeProvider`. Elegís el tema visual con la prop `theme`:
 
 ```tsx
-import { ThemeProvider, Button, Card, Badge } from '@conatel-sa/react-ui';
+import { ThemeProvider } from '@conatel-sa/react-ui';
 
 function App() {
   return (
-    <ThemeProvider theme="conatel"> {/* o "vivion" */}
+    <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
+
+```tsx
+import { ThemeProvider, Button, Card, CardBody, Badge } from '@conatel-sa/react-ui';
+
+function Ejemplo() {
+  return (
+    <ThemeProvider theme="conatel" as="div">
       <Card>
-        <Badge variant="success">Activo</Badge>
-        <Button variant="primary">Confirmar</Button>
+        <CardBody>
+          <Badge variant="success">Listo</Badge>
+          <Button variant="primary">Continuar</Button>
+        </CardBody>
       </Card>
     </ThemeProvider>
   );
 }
 ```
 
-## Theming
+---
 
-La librería soporta dos temas de marca que se aplican a todos los componentes:
+## Temas (resumen)
 
-| Tema | Color primario | Uso |
-|---|---|---|
-| `conatel` | `#CC032E` | Productos Conatel |
-| `vivion` | `#0098D4` | Productos Vivion |
+| Valor en código | Color principal aproximado | Uso típico |
+|-----------------|----------------------------|------------|
+| `conatel` | Rojo `#CC032E` | Identidad corporativa Conatel |
+| `vivion` | Azul `#0098D4` | Identidad Vivion |
 
 ```tsx
-<ThemeProvider theme="vivion">
-  <Button variant="primary">Vivion</Button>
+<ThemeProvider theme="vivion" as="div">
+  <Button variant="primary">Acción principal</Button>
 </ThemeProvider>
 ```
 
-## Componentes disponibles
+---
+
+## Si usás un asistente de código (opcional)
 
-### Tipografía
-`Heading` - `Text`
+Texto de referencia que podés pegar para alinear criterios (no es obligatorio):
 
-### Formularios
-`Input` - `Textarea` - `Select` - `Checkbox` - `Toggle` - `FormField`
+> 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.
 
-### Feedback
-`Badge` - `Alert` - `Spinner` - `Progress`
+---
 
-### Contenedores
-`Card` - `CardHeader` - `CardBody` - `CardFooter` - `Modal`
+## Qué incluye el paquete principal
 
-### Navegación
-`Navbar` - `NavItem` - `Tabs` - `TabList` - `Tab` - `TabPanel`
+Import: `import { … } from '@conatel-sa/react-ui'`
 
-### Datos
-`Table` - `TableHead` - `TableBody` - `TableRow` - `TableCell` - `TableHeaderCell`
+| Á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` |
 
-### Miscelánea
-`Avatar` - `Divider` - `EmptyState` - `Button` - `Sidebar` - `SidebarItem` - `Toast` - `ScoreSelector`
+---
 
-### Iconos (subpath `@conatel-sa/react-ui/icons`)
+## Módulos opcionales (subrutas)
 
-Material Symbols y envoltorio opcional para `lucide-react`:
+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
 
 ```tsx
 import { Icon, IconProvider } from '@conatel-sa/react-ui/icons';
 import '@conatel-sa/react-ui/dist/material-symbols.css';
 
-function WithIcons() {
+function ConIconos() {
   return (
-    <ThemeProvider theme="conatel">
+    <ThemeProvider theme="conatel" as="div">
       <IconProvider injectStylesheet defaultSize="md">
         <Icon name="search" size="md" />
       </IconProvider>
@@ -91,20 +183,34 @@ function WithIcons() {
 }
 ```
 
-`lucide-react` es opcional (solo si usás `LucideIcon`).
+`lucide-react` es **opcional** (solo si usás `LucideIcon`).
 
-## Subpaquetes opcionales
+### Ejemplo: formularios extendidos
 
-| Subpath | Contenido resumido |
-|---------|---------------------|
-| `@conatel-sa/react-ui/forms` | `PasswordInput`, `MultiSelectDropdown` |
-| `@conatel-sa/react-ui/cards` | `ServiceCard`, `FeatureCard`, `ChangelogPanel`, `ArtifactReportCard` |
-| `@conatel-sa/react-ui/dialogs` | `ChangelogDialog` (requiere `react-dom`) |
-| `@conatel-sa/react-ui/metrics` | `StatInline`, `MiniMeter` |
-| `@conatel-sa/react-ui/status` | `StatusSummaryPopover` |
+```tsx
+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';
+```
 
-En las demos HTML, `library-gallery-new.html` carga `dist/forms.umd.js`, `cards.umd.js`, `dialogs.umd.js`, `metrics.umd.js`, `status.umd.js` (además de `icons.umd.js`) y fusiona los globales en `window.ReactLibrary`. Ver `docs/SUBPACKAGES.md` en el workspace react-ui.
+---
+
+## 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 incluye tipos. No se requiere `@types` adicional para este paquete.
+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](https://www.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conatel-sa/react-ui",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Biblioteca de componentes React para productos Conatel y Vivion. Incluye más de 20 componentes UI con theming. Subpaquetes opcionales: ./icons, ./forms, ./cards, ./dialogs, ./metrics, ./status.",
   "main": "dist/index.umd.js",
   "module": "dist/index.mjs",
@@ -46,7 +46,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "dev": "vite",