React-lib-amf NPM

ui-react-components-ui

ui-react-components-ui es una librería de componentes y estilos para su uso en los diferentes portales de Unuhi. Es totalmente configurable, lo cual significa que el desarrollador puede agregar, modificar o remover algún elemento siguiendo la estructura de carpetas y archivos que se mencionará más adelante en este README.

ui-react-components-ui

Requisitos

Git 2.28+
NodeJs 16.18+
npm 8.19+
Visual Studio Code 1.78+
Usuario y contraseña del Nexus Repository. Asegúrate de tener el acceso a los repositorios snapshot, release y group, ya que de éste se descargarán las dependencias necesarias, así como también se utilizará para la publicación de la librería.
Usuario y contraseña del SonarQube. Asegúrate de tener acceso al espacio de este proyecto sobre la plataforma de SonarQube, esto para llevar a cabo el análisis de código fuente.

Estructura del proyecto

El código equivalente a la librería engloba al espacio de trabajo desde raíz del proyecto. Dentro del proyecto de la librería se encontrarán las siguientes carpetas y archivos:

.
|-- src/
|   |-- __mocks__/
|   |-- __test__/
|   |-- assets/
|   |   |-- components/
|   |   |-- core/
|   |   |-- layout/
|   |   |-- _init.scss
|   |   └── styles.scss
|   |-- components/
|   |   |-- button/
|   |   |-- checkbox/
|   |   |-- dateInput/
|   |   |-- dropDown/
|   |   |-- input/
|   |   |-- loader/
|   |   |-- pagination/
|   |   |-- radio/
|   |   |-- select/
|   |   |-- selectAsync/
|   |   |-- selectForm/
|   |   └── index.tsx
|   |-- hooks/
|   |   |-- usePagination.ts
|   |   |-- index.ts
|   |-- utils/
|   |   |-- ConstansUtil.ts
|   |   |-- ValidateNumber.ts
|   |   |-- index.ts
|   |-- declarations.d.ts
|   └── index.ts
|-- .babelrc
|-- .eslintrc.js
|-- .prettierrc.js
|-- .lintstagedrc.js
|-- .gitignore
|-- .commitlint.config.js
|-- .jest.config.js
|-- .jest.setup.js
|--  CHANGELOG.md
|-- .package.json
|-- .README.md
|-- rollup.config.mjs
└── tsconfig.json

Principales tecnologías de desarrollo

React
Typescript
Rollup
NPM

Dependencias con servicios y proyectos

Inicio rápido

Si la libreria cuenta con elementos visuales, es posible que desees validar que estos se visualicen correctamente en tu proyecto, así como validar la descarga de dependencias de manera correcta.

Los comandos descritos en los siguientes pasos pueden ser aplicados sobre Windows, Linux o macOS

Validar la instalación, configuración y versión de las herramientas desde tu terminal favorita:
Git:
```
git version
```
NodeJs:
```
node -v
```
npm:
```
npm -v
```
Clonar el proyecto sobre tu espacio de trabajo:
```
git clone $URL_REPOSITORY
```
Validar que se encuentre disponible el Nexus Repository.
Para la construcción del la librería es necesaria la instalación de las dependencias minímas especificadas en el package.json del proyecto, además, si el proyecto necesita alguna dependencia extra, sobre la carpeta raíz (espacio de trabajo) del proyecto, descargar las dependencias. Asegúrate de configurar de manera correcta los profiles npmrc, ya que la descarga de las dependencias serán mediante el Nexus Repository:
```
npmrc $PROFILE_NAME_GROUP
```
```
npm install
```
Si deseas agregar una dependencia extra, asegúrate de agregarla en modo desarrollador, por ejemplo:
```
npm install --save-dev $NOMBRE_DE_LA_DEPENDENCIA
```
Con esto aseguramos la descarga y compilación correcta del proyecto.
Para la instalación de esta librería dentro de un proyecto, es posible que ésta no se encuentre en un sistema de gestión de paquetes público. En éste caso existen dos posiblidades:
1. Si cuentas con perfiles npmrc, asegúrate de configurar de manera correcta el perfil donde se descargan las dependencias:
```
    npmrc $PROFILE_NAME_GROUP
```
```
    npm install ui-react-components-ui
```
2. Si no se cuenta con una configuración de perfiles, es necesario agregar el archivo .npmrc al proyecto en donde instalarás la librería, ya que la librería no se encuentra de manera pública en npmjs y no podrás realizar la instalación. El contenido de tu archivo debería ser semejante al de las siguientes líneas:
```
registry=https://${YOUR_PRIVATE_REGISTRY}/
//${YOUR_PRIVATE_REGISTRY}//:\_authToken=${YOUR_PRIVATE_TOKEN}
```
Si esta librería sí se encuentra en un sistema de gestión de paquetes público, es decir, no es privada, la instalación de la librería se puede realizar desde el perfil por default.
```
    npmrc default
```
```
    npm install ui-react-components-ui
```

Ejecución de pruebas unitarias

Agregar aquí los pasos aplicados para poder ejecutar pruebas.

Validación de libreria de forma local

Los comandos descritos en los siguientes pasos pueden ser aplicados sobre Windows, Linux o macOS

Para validar de manera local antes de realizar la publicación sobre el Nexus Repository, es necesario seguir los siguientes pasos:

En caso de que tengas instalada esta librería de manera global, es decir, que la hayas descargado directamente del Nexus Repository, y para evitar una colisión con la prueba local, es necesario desinstalar la versión instalada globalmente. Puedes validar previamente si cuentas con ella:
```
npm list -g ui-react-components-ui
```
Si encuentra la dependencia, puedes desinstalarla, en caso de que no, no es necesario:
```
npm uninstall -g ui-react-components-ui
```
Sobre la ruta ./ui-react-components-ui/, construir y compilar la librería:
Es importante que se haga sobre esta ruta, es decir, la equivalente a la librería.
Para poder ejecutar el compando npm run rollup en Windows es necesario hacerlo con el bash de git en la raíz del proyecto.
```
npm run rollup
```
Tras la construcción y compilación del proyecto, se generará la carpeta dist/ sobre la carpeta raíz del proyecto. Ubicado en la raiz del proyecto, ejecutar el enlace simbólico para poder utilizar la librería como una dependencia localmente:
```
npm link
```
Este comando creará un enlace simbólico en el registro local de npm.
Ya en el proyecto donde se requiere utilizar y probar la librería antes de publicarla en el Nexus Repository, sobre la carpeta raíz del proyecto, ejecutar el enlace simbolico de la librería:
```
npm link ui-react-components-ui
```
Esto permitirá mantener el enlace simbólico de la dependencia (librería) en el proyecto, es decir, apuntará a la carpeta dist que se estableció en el punto 3, de esta forma el proyecto en cuestión podrá reconocer la dependencia como si se hubiera descargado de algún repositorio como nexus o npmjs.
Los pasos 3 y 4 son enlaces simbólicos, única y exclusivamente para validar y probar los cambios que se pudieran presentar sobre la librería de manera local antes de publicarla. Esto debe estar reforzado con la ejecución de las pruebas unitarias.
De esta forma podras visualizar la 'importación' sobre el node_modules en el proyecto donde se quiere probar y poder utilizar la librería en donde lo requieras, por ejemplo:
```
import { Button } from 'ui-react-components-ui'

//Other code

return (
  <>
    <Button label={'Mi boton'}></Button>
  </>
)

//Other code
```
Una vez concluidas las pruebas y listo para publicar sobre el Nexus Repository y poder utilizar la librería de manera formal directamente desde la descarga de la dependencia, es necesario romper el enlace simbólico, tanto en el proyecto donde se probó, como en esta librería.
Primero, sobre la carpeta raíz del proyecto donde se probó (esto provocará que se generen problemas de compilación con el código que se incluyó para probar):
```
npm unlink ui-react-components-ui
```
Finalmente, sobre la carpeta ./ui-react-components-ui del la librería, raíz del proyecto:
```
npm unlink
```
De esta forma ambos enlaces simbólicos ya no estarán presentes y, al buscar la dependencia, ésta ya no estará disponible:
```
npm list -g ui-react-components-ui
```

Análisis de código fuente (SonarQube)

Los comandos necesarios para el análisis deben ser agregados aquí y especificar si estos pasos pueden ser aplicados sobre Windows, Linux o macOS.

Para realizar el análisis de código fuente sobre el SonarQube considerando el reporte de cobertura, ejecutar previamente las pruebas unitarias descritas en ejecución de pruebas unitarias, esto sobre la carpeta raiz (espacio de trabajo) del proyecto.

Construcción de libreria y publicación en Nexus Repository Manager

IMPORTANTE: La publicación de la librería implica sobreescribir una misma versión o bien una totalmente diferente a las ya publicadas en el Nexus Repository. Los comandos descritos en los siguientes pasos pueden ser aplicados sobre Linux o macOS, si deseas aplicar los comando en Windows, puedes usar el bash de git.

Asegurar la instalación de los paquetes, compilación y validación del proyecto descrito en los apartados inicio rápido, ejecución de pruebas unitarias y validación de libreria de forma local asegurando el correcto funcionamiento.
Modificar la versión sobre ./ui-react-components-ui/package.json, "version": "x.y.z", validando que ésta no se encuentre ya publicada en el Nexus Repository. La versión debe ser con base la estructura x.y.z:
```
x: Cambios mayores, versión mayor
y: Actualización menor, se agregan funciones o flujos
z: Solución de issues o inclusión de parches.
```
Sobre la ruta ./ui-react-components-ui, construir y compilar la libreria:

Es importante que se haga sobre esta ruta, es decir, la equivalente a la libreria.

npm run rollup

Tras la construcción y compilación de la librería, se generará la carpeta dist/ sobre la carpeta raíz (espacio de trabajo) del proyecto. El contenido de esta carpeta será lo que se publicará sobre el Nexus Repository, dependiendo de la versión y lugar de publicación; snapshot o release.

Validar estar en el profile npm correcto y, sobre la carpeta ./ui-react-components-ui, es decir, la raíz del proyecto, ejecutar la publicación de la librería.

npmrc $PROFILE_NAME_SNAPSHOT o $PROFILE_NAME_RELEASE

npm publish

Al publicar de manera exitosa se obtendrá un resultado similar al siguiente:

npm notice 📦 ui-react-components-ui@0.0.1
npm notice === Tarball Contents ===
...
npm notice === Tarball Details ===
npm notice name: ui-react-components-ui
npm notice version: 0.0.1
npm notice filename: ui-react-components-uib0.0.1.tgz
npm notice package size: 4.6 kB
npm notice unpacked size: 20.3 kB
npm notice shasum: 06560d6b85d1c5348ecb2cb58e3cd5ef19a648ad
npm notice integrity: sha512-CuiGLhJdgYaFx[...]csL/kXQXsZg5w==
npm notice total files: 37
npm notice
+ ui-react-components-ui@0.0.1

De esta forma ya es posible descargar/instalar la dependencia de forma directa del Nexus Repository, considerando el nombre y versión de la dependencia, tomando en cuenta que ésta debe descargarse del repositorio group (npm-group).

Cambio de profile:

npmrc $PROFILE_NAME_GROUP

Instalación sobre proyecto

npm install ui-react-components-ui@$VERSION

Instalación global:

npm install -g ui-react-components-ui@$VERSION

Importación de elementos

Hooks, funciones y componentes

Para el uso de hooks, funciones y/o componentes desde el proyecto donde se instalará esta librería, es necesario realizarlo de la siguiente manera:

import { COMPONENTE, HOOK, FUNCION } from 'ui-react-components-ui'

El nombre con el que se importará el componente, hook o función será con el indicado en el index de hooks, componentes y utils de nuestra librería.

Variables Sass

La Librería contiene un fichero scss de variables por default que se utilizan en el resto de estilos de los componentes.

Importación

Se recomienda evitar modificar los archivos Sass de origen. Es posible que deseemos crear una estructura como la siguiente, con un archivo de personalización de scss, por ejemplo, custom.scss o styles.scss:

proyecto/
|-- assets/
|   └── styles/
|   |  └── styles.scss
└── node_modules/ui-react-components-ui
    |-- dist/
    └── src/
        └── assets/

En nuestro archivo custom.scss o styles.scss, se importarán los archivos Sass de origen, por ejemplo el archivo styles.scss e incluir las variables por default que desean sobreescribir.

// styles.scss

// Aquí las variables por default que necesitamos sobreescribir, ejemplo:
$input-bg: #13c8a1;
$input-focus-border: 1px solid #0881de;
@import '~ui-react-components-ui/src/assets/styles';

Posteriormente importar el archivo custom.scss en nuestro archivo index.tsx o App.tsx o donde sea requerido, si no se desea modificar nada, sólo hacer el import del archivo de origen Sass.

// App.tsx
// Para el caso donde no deseamos modificar variables, importar el archivo Sass de origen
import 'ui-react-components-ui/dist/assets/styles.scss'

// App.tsx
// Para el caso donde deseamos modificar variables, importar el archivo custom, que importará los archivos de origen de la librería.
import './assets/styles.scss'

Variables default

Lista de variables con el indicador default que permite sobreescribir el valor predeterminado.

// Color system
$white: #ffffff !default;
$black: #000000 !default;
$gray-bg: #f3f6f9 !default;

// Primary colors
$primary: #2167ae !default;
$primary-active: #0095e8 !default;
$primary-light: #e6f4f9 !default;
$primary-light-dark: #23366f !default;
$primary-inverse: $white !default;

// Success colors
$success: #77a984 !default;
$success-active: #638e6e !default;
$success-light: #8fc89e !default;
$success-light-dark: #1c3833 !default;
$success-inverse: $white !default;

// Info colors
$info: #8950fc !default;
$info-active: #7337ee !default;
$info-light: #eee5ff !default;
$info-light-dark: #2f264f !default;
$info-inverse: $white !default;

// Warning colors
$warning: #fff773 !default;
$warning-active: #f5ed57 !default;
$warning-light: #fefaaf !default;
$warning-light-dark: #392f28 !default;
$warning-inverse: $white !default;

// Danger colors
$danger: #e75665 !default;
$danger-active: #ff7569 !default;
$danger-light: #ffe2e5 !default;
$danger-light-dark: #3a2434 !default;
$danger-inverse: $white !default;

FAQs y troubleshooting

Obtengo un error 400 Bad Request al publicar la versión

Es muy probable que estés intentando publicar la misma versión de la librería, mismo que el Nexus Repository lo permite por seguridad a reemplazar por error la misma versión.

Considerar los siguientes escenarios:

Realmente es necesario sobreescribir la versión:
1. Ingresar al Nexus Repository e iniciar sesión
2. Ingresar al menu Browse
3. Seleccionar el repositorio correspondiente, ya sea; npm-snapshot o npm-release
4. Ubicar la dependencia ui-react-components-ui y seleccionar la carpeta
5. Seleccionar la versión que se quiere reemplazar y eliminarla con la opción Delete asset
Publicar una nueva versión sin afectar las que ya están publicadas:
1. Modificar la versión de la libreria siguiendo el paso 2 de la sección Construcción de libreria y publicación en Nexus Repository Manager
2. Publicar la librearia considerando los pasos 1 y 3 de la sección Construcción de libreria y publicación en Nexus Repository Manager

Obtengo un error del tipo 'ui-react-components-ui has no exported member...'

Considerar los siguientes escenarios:

Deten la ejecución del servidor de tu proyecto ctrl + c y vuelve a iniciarlo npm start
Asegúrate de que si agregaste una carpeta a la estructura de archivos, contenga su respectivo archivo index.ts que exporte todo el contenido deseado. Además asegúrate de incluir la exportación de esa carpeta en el archivo index.ts ubicado en la ruta **./src
Si sólo agregaste un archivo extra a la estructura original, asegúrate de que tenga una etiqueta export o export default y que sea agregado ese export a su index.ts correspondiente.

Al importar hooks, se obtienen errores por reglas de hooks

Verifica que en el configuración de rollup, en el archivo rollup.config.mjs se encuentra la propiedad external en el mismo objeto con la propiedad output con las opciones de formato en cjs y esm, la propiedad external debe contener mínimo en su matriz la palabra react para no causar una doble importación de la dependencia de react.

      {
        input: 'src/index.ts',
        output: [
          {
            file: packageJson.main,
            format: 'cjs',
            sourcemap: false,
          },
          {
            file: packageJson.module,
            format: 'esm',
            sourcemap: false,
          },
        ],
        plugins: [
          //plugins
        ],
        external: ['react', 'react-dom']
      }

@everything-registry/sub-chunk-2564

0.0.2

6 months ago