cemtrik-dependencies 1.0.225 → 1.0.227

package/README.md

@@ -1,10 +1,337 @@
-# React + Vite
+# Cemtrik Dependencies
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Una biblioteca completa de componentes React diseñada para construir interfaces de usuario
+consistentes, accesibles y modernas en aplicaciones Cemtrik. Esta biblioteca sigue los principios de
+Atomic Design e incluye un espacio de trabajo Storybook completo para documentacion y exploracion de
+componentes.
 
-Currently, two official plugins are available:
+## Que Hace Este Proyecto
 
--   [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md)
-    uses [Babel](https://babeljs.io/) for Fast Refresh
--   [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses
-    [SWC](https://swc.rs/) for Fast Refresh
+Cemtrik Dependencies es una **biblioteca de componentes UI React** que proporciona:
+
+-   **Componentes React Reutilizables**: Una coleccion de mas de 28 componentes UI organizados
+    siguiendo la metodologia Atomic Design
+-   **Hooks React Personalizados**: 4 hooks potentes para gestion de formularios, manejo de modales
+    y diseno responsivo
+-   **Funciones de Utilidad**: Funciones auxiliares para operaciones comunes como validacion de
+    correo electronico, agrupacion de datos y gestion de nombres de clases
+-   **Documentacion Completa**: Espacio de trabajo Storybook interactivo con cambio de marca
+    dinamico y documentacion completa de componentes
+
+La biblioteca esta construida para garantizar **consistencia**, **accesibilidad** (WCAG 2.1 AA) y
+**experiencia de desarrollador** en todas las aplicaciones Cemtrik.
+
+---
+
+## Caracteristicas y Modulos
+
+### Componentes (Organizados por Atomic Design)
+
+#### Atomos (20 componentes)
+
+Bloques basicos de construccion de la UI:
+
+| Componente                       | Descripcion                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `Alert`                          | Mensajes de retroalimentacion para acciones del usuario |
+| `Avatar`                         | Representacion de usuario con iniciales o imagenes      |
+| `Bullets`                        | Indicadores de navegacion                               |
+| `ButtonSolid`                    | Botones primarios solidos                               |
+| `ButtonOutline`                  | Botones secundarios con contorno                        |
+| `ButtonPagination`               | Botones de control de paginacion                        |
+| `Checkbox`                       | Controles de seleccion multiple                         |
+| `ConfirmationAbandoningCreation` | Dialogos de confirmacion                                |
+| `Divider`                        | Separadores visuales                                    |
+| `GoBack`                         | Botones de navegacion hacia atras                       |
+| `Image`                          | Componente de imagen optimizado                         |
+| `Input`                          | Campos de entrada de texto                              |
+| `InputDropdown`                  | Campos de entrada desplegables                          |
+| `Select`                         | Selectores de opciones                                  |
+| `SelectColor`                    | Selectores de color                                     |
+| `Spinner`                        | Indicadores de carga                                    |
+| `Switch`                         | Interruptores de alternancia                            |
+| `Textarea`                       | Entradas de texto de multiples lineas                   |
+| `Tooltip`                        | Ventanas emergentes informativas                        |
+
+#### Moleculas (6 componentes)
+
+Combinaciones complejas de atomos:
+
+| Componente          | Descripcion                      |
+| ------------------- | -------------------------------- |
+| `CoverPhoto`        | Componentes de imagen de portada |
+| `Dropdown`          | Menus desplegables complejos     |
+| `IconSelectPicker`  | Interfaz de seleccion de iconos  |
+| `Modal`             | Ventanas de dialogo              |
+| `Pagination`        | Sistemas completos de paginacion |
+| `SketchColorPicker` | Seleccion avanzada de colores    |
+
+#### Plantillas (1 componente)
+
+Estructuras a nivel de pagina:
+
+| Componente  | Descripcion                      |
+| ----------- | -------------------------------- |
+| `Accordion` | Paneles de contenido colapsables |
+
+### Hooks
+
+| Hook                  | Descripcion                                     |
+| --------------------- | ----------------------------------------------- |
+| `useForm`             | Gestion de estado de formularios con validacion |
+| `useCloseModal`       | Manejar cierre de modales al hacer clic fuera   |
+| `useMediaQuery`       | Deteccion de puntos de ruptura responsivos      |
+| `useWindowDimensions` | Seguimiento de cambios de tamano de ventana     |
+
+### Utilidades
+
+| Funcion                  | Descripcion                                 |
+| ------------------------ | ------------------------------------------- |
+| `copyOptions`            | Clonacion profunda de arrays de objetos     |
+| `classNames`             | Fusion condicional de clases CSS            |
+| `validateEmail`          | Validacion de formato de correo electronico |
+| `generateAvatarInitials` | Generar iniciales a partir de nombres       |
+| `groupBy`                | Agrupar elementos de array por clave        |
+| `isPromise`              | Verificar si un valor es una Promesa        |
+
+### Caracteristicas de Storybook
+
+-   **4 Temas Dinamicos**: Cambiar entre marcas sin reconstruir
+    -   Cemtrik (corporativo)
+    -   Modo Oscuro
+    -   Naturaleza (tonos verdes)
+    -   Oceano (tonos azules)
+-   **Documentacion en Espanol**: Toda la documentacion en espanol
+-   **Accesibilidad**: Cumple con WCAG 2.1 AA
+-   **Controles Interactivos**: Modificar props en tiempo real
+-   **Descubrimiento de Componentes**: Deteccion automatica de nuevos componentes
+
+---
+
+## Arquitectura de Componentes
+
+La biblioteca esta organizada siguiendo los principios de Atomic Design:
+
+-   **Atomos**: Componentes basicos como botones, entradas e iconos
+-   **Moleculas**: Combinaciones de atomos como modales y dropdowns
+-   **Plantillas**: Estructuras de pagina como acordeones
+
+Los componentes, hooks y utilidades se exportan desde el archivo principal `index.js` y estan
+documentados en el espacio de trabajo Storybook con temas dinamicos.
+
+---
+
+## Stack Tecnologico
+
+### Tecnologias Principales
+
+| Categoria       | Tecnologia   | Version | Proposito                         |
+| --------------- | ------------ | ------- | --------------------------------- |
+| **Framework**   | React        | 18.2.0  | Biblioteca UI                     |
+| **Build Tool**  | Vite         | 5.4.0   | Desarrollo rapido y empaquetado   |
+| **Estilos**     | Tailwind CSS | Latest  | CSS utility-first                 |
+| **Iconos**      | Heroicons    | 2.0.18  | Biblioteca de iconos SVG          |
+| **Componentes** | Headless UI  | 1.7.15  | Componentes accesibles sin estilo |
+
+### Documentacion y Desarrollo
+
+| Tecnologia           | Proposito                              |
+| -------------------- | -------------------------------------- |
+| **Storybook**        | Documentacion y pruebas de componentes |
+| **Vite** (Storybook) | Sistema de construccion de Storybook   |
+| **MDX**              | Documentacion con JSX                  |
+
+### Calidad de Codigo
+
+| Tecnologia                | Proposito                          |
+| ------------------------- | ---------------------------------- |
+| **ESLint**                | Linting de JavaScript/React        |
+| **Prettier**              | Formateo de codigo                 |
+| **Husky**                 | Git hooks                          |
+| **Commitlint**            | Convenciones de mensajes de commit |
+| **Jest**                  | Pruebas unitarias                  |
+| **React Testing Library** | Pruebas de componentes             |
+
+### Gestion de Paquetes
+
+| Tecnologia | Proposito                   |
+| ---------- | --------------------------- |
+| **npm**    | Gestion de paquetes         |
+| **Babel**  | Transpilacion de JavaScript |
+
+---
+
+## Instalacion
+
+### Requisitos Previos
+
+-   Node.js 16+
+-   npm 8+ o yarn 1.22+
+
+### Instalar como Dependencia
+
+```bash
+npm install cemtrik-dependencies
+```
+
+### Dependencias de Pares
+
+Los siguientes paquetes deben estar instalados en tu proyecto:
+
+```bash
+npm install react react-dom
+npm install @headlessui/react @heroicons/react classnames
+```
+
+### Configuracion de Desarrollo
+
+1. **Clonar o navegar al repositorio:**
+
+```bash
+cd cemtrik-dependencies
+```
+
+2. **Instalar dependencias:**
+
+```bash
+npm install
+```
+
+3. **Iniciar servidor de desarrollo:**
+
+```bash
+npm run dev
+```
+
+4. **Ejecutar pruebas:**
+
+```bash
+npm test
+```
+
+5. **Ejecutar linter:**
+
+```bash
+npm run lint
+```
+
+6. **Construir para produccion:**
+
+```bash
+npm run build
+```
+
+### Configuracion de Storybook
+
+1. **Instalar dependencias de Storybook:**
+
+```bash
+cd storybook
+npm install
+```
+
+2. **Iniciar Storybook:**
+
+```bash
+# Desde el directorio raiz
+npm run storybook
+
+# O desde el directorio storybook
+cd storybook && npm run storybook
+```
+
+3. **Abrir en navegador:**
+
+Navega a `http://localhost:6006`
+
+---
+
+## Inicio Rapido
+
+### Usar Componentes
+
+```jsx
+import { ButtonSolid, Input, useForm } from "cemtrik-dependencies";
+
+function MyForm() {
+    const { handleSubmit, handleChange, model, messageError } = useForm();
+
+    const onSubmit = (data) => {
+        console.log("Form data:", data);
+    };
+
+    return (
+        <form onSubmit={handleSubmit(onSubmit)}>
+            <Input
+                name="email"
+                onChange={(e) => handleChange(e, setForm, form)}
+                placeholder="Enter email"
+            />
+            {messageError.email && <span>{messageError.email}</span>}
+
+            <ButtonSolid type="submit">Submit</ButtonSolid>
+        </form>
+    );
+}
+```
+
+### Usar Utilidades
+
+```jsx
+import { validateEmail, classNames, groupBy } from "cemtric-dependencies";
+
+// Validacion de correo
+const isValid = validateEmail("user@example.com"); // true
+
+// Clases condicionales
+const buttonClass = classNames("btn", isPrimary && "btn-primary", isDisabled && "btn-disabled");
+
+// Agrupar elementos de array
+const grouped = groupBy({
+    items: users,
+    key: "department",
+});
+```
+
+---
+
+## Scripts Disponibles
+
+| Script                       | Descripcion                               |
+| ---------------------------- | ----------------------------------------- |
+| `npm run dev`                | Iniciar servidor de desarrollo Vite       |
+| `npm run build`              | Construir biblioteca para produccion      |
+| `npm run preview`            | Previsualizar construccion de produccion  |
+| `npm test`                   | Ejecutar pruebas Jest                     |
+| `npm run coverage`           | Ejecutar pruebas con reporte de cobertura |
+| `npm run lint`               | Ejecutar ESLint                           |
+| `npm run format`             | Formatear codigo con Prettier             |
+| `npm run storybook`          | Iniciar servidor de desarrollo Storybook  |
+| `npm run build-storybook`    | Construir Storybook para produccion       |
+| `npm run storybook:generate` | Regenerar documentacion de Storybook      |
+
+---
+
+## Licencia
+
+Copyright 2024 Cemtrik. Todos los derechos reservados.
+
+---
+
+## Contribuir
+
+1. Asegurate de que tu codigo siga el estilo existente (ESLint + Prettier)
+2. Escribe pruebas para nuevas caracteristicas
+3. Actualiza la documentacion en Storybook
+4. Sigue mensajes de commit convencionales
+5. Ejecuta `npm run lint` antes de hacer commit
+
+---
+
+## Soporte
+
+Para preguntas o soporte:
+
+-   Consulta la documentacion de Storybook en `http://localhost:6006`
+-   Revisa las implementaciones de componentes existentes en `src/components/`
+-   Consulta el resumen de implementacion en `storybook/RESUMEN_IMPLEMENTACION.md`