genexus-ide-ui

GeneXus Ide Ui

GeneXus Ide Ui la biblioteca de componentes diseñada para el IDE Web de GeneXus.

• Participantes
• Specs. y Status
• Estructura 'src' folder
• Buenas prácticas
• Gxg-container
• Grillas
• Gemini
• Flujo de trabajo
• Consideraciones
• Readme StencilJs
• Links de interés

Participantes

• Andrés Laplace | Lead Product Designer
• Bruno Sastre | Front End Developer
• Daniel Mariño | Code & Quality Reviewer
• Diego Scaffo | (Falta)
• Germán Asiz | GeneXus Web es Engineering Leader
• Mauro Canziani | Head of Design
• Natalia Rudomín | Product Designer
• Nicolás Cámera | Code & Quality Reviewer
• Orlando Pantoja | Front End Developer
• Daniel Piad | Front End Developer

Specs. y Status

Las specs. de los componentes se encuentran en esta carpeta doc.
El estado de los componentes se encuentra en esta planilla

Estructura 'src' folder

📁 common

Aquí van archivos comunes a todo el proyecto. Pueden agregarse mas si es necesario.

helper-functions.tsx

Funciones auxiliadoras.

interfaces.ts

Interfaces. Se solicita usar el prefijo Gx : GxInterfaceName

locale.ts

Este archivo se encarga de manejar la lógica relacionada a las traducciones. En principio no debería modificarse.

types.ts

Definicion de tipos.

📁 components

Aquí van los componentes. _template es un componente vacío, que solo tiene la estructura básica para comenzar el desarrollo de un componente nuevo. Por favor, duplicar esta carpeta y cambiar los nombres cuando haya que crear un nuevo componente.

📁 global

Aquí van las hojas de estilos .scss. Se sugiere ser organizado, y crear una hoja por cada 'asunto'.

📁 pages

Aquí van las paginas html para probar y mostrar los componentes. Hay que crear una pagina por cada componente. El nombre de la pagina debe ser [nombre-del-componente].html sin el prefijo:

✅ new-kb.html
❌ gx-ide-new-kb.html

Cuando se vaya a crear una nueva pagina.html para un componente nuevo, hay que duplicar _template.html y modificarlo. La razón, es que ya hay una estructura definida, y queremos respetarla.

• Cada pagina tiene un sidebar, con un conjunto de botones que permiten probar funcionalidades comunes a todos los componentes: dark-mode, rtl, validación, etc.
• Cada pagina tiene asociada una hoja de estilos (dev-styles.css) que es necesaria para la correcta visualización de la pagina.

📃 index.html

Index.html se abre al ejecutar npm start.
Muestra dos listas de componentes: 'completed' | 'in progress'.
Para agregar un componente a cualquiera de esas dos listas, solo es necesario agregar el nombre del item (sin el prefijo) al array correspondiente. Ej.:

✅
const completed = ["new-kb"];
const inProgress = ["my-new-component"];

❌
const completed = ["gx-ide-new-kb"];
const inProgress = ["gx-ide-my-new-component"];

Buenas prácticas

Seguir durante el desarrollo el documento de buenas prácticas (Se requiere acceso a la vpn de Genexus).

• Intentar desarrollar los Web Components usando Shadow DOM.
• Si dan los tiempos y la experiencia, evitar implementar los controles usando una liberaría.
• Siempre pensar en la accesibilidad de los componentes.
• Aprovechar al máximo posible el componente funcional <Host>.
• Diseñar el estilizado de los componentes pensando en el soporte para RTL.
• Evitar el colisionamiento de nombres de clases lo mejor que se pueda. Escribir nombres de clases bien específicos.
• Evitar el colisionamiento de nombres de variables CSS lo mejor que se pueda. Escribir nombres de variables bien específicos.
• Escribir los selectores CSS de modo que terminen en un .class siempre que sea posible.
• Evitar usar !important en las propiedades CSS.
• Evitar estilizar los componentes usando clases predefinidas por otra dependencia.
• Documentar siempre las propiedades, eventos y métodos.
• Incluir un ejemplo de uso de los componentes y una descripción de la utilidad.
• Documentación para las parts y slots de los componentes siempre útil.
• Documentación para las variables CSS (custom vars) de los componentes siempre útil.
• Ordenar el código siguiendo los patrones recomendados.
• Las funciones no deberían hacer muchas cosas.
• Definir las variables y funciones con private tanto como sea posible.
• Tipar todas las variables y parámetros de funciones siempre que sea posible.
• Usar siempre nombres de variables y funciones mnemotécnicos, sin importar el largo de las mismas.
• No incluir estilos fijos en el render de los componentes.
• Documentar siempre las funciones que sean muy avanzadas.
• Evitar los strings y números mágicos.
• Crear interfaces para tipar la estructura de objetos sin tipo.
• Utilizar template literals y funciones de JavaScript para crear strings complejos.
• Utilizar cláusulas guarda para evitar las sentencias if anidadas.
• Evitar chequear la existencia de un objeto comprobando con null o undefined.
• Evitar ifs de una sola línea (sin brackets).
• Evitar implementar los Switch Case funcionales de manera imperativa. Usar objetos con lookups en cambio.
• Los comentarios no sobran. Hacen falta.
• Agregar tests unitarios para los componentes :)

Gxg-container

En cualquier componente del ide web, es probable que sea necesario maquetar "cajas" que contengan el contenido. Estas cajas podrán además tener o no un título, y/o un footer. Para mantener la consistencia de estas cajas a lo largo de todos los componentes, se creó el componente auxiliar gxg-container. Por favor, usarlo siempre que sea necesario. Hay una página donde se puede ver el uso del componente con sus diferentes estados, y al final se muestra una tabla con las properties disponibles.

Esa página está disponible en: http://localhost:3333/pages/gxg-container.html

Grillas

Se sugiere el uso de grillas siempre que sea posible. La configuración de la grilla es distinta en cada caso, por lo que es responsabilidad del desarrollador definirla en cada caso. Sin embargo, toda grilla deberá tener presente la clase auxiliar grid, que además de definir al contenedor como display:grid ya define el valor del gap. El fin es mantener la consistencia del gap entre todas las grillas de todos los componentes.

Gemini

Esta biblioteca va a estar basada en componentes de Gemini. Para ver los componentes disponibles y sus propiedades y eventos hay dos fuentes: El showcase de Storybook, o el repositorio.

Showcase Gemini

En la pestaña Notes se pueden ver las properties

Repositorio Gemini

• npm install
• npm start

Se abrirá la página principal, con un listado de links a todos los componentes disponibles. Cada componente tiene su propia página html. Siéntanse libres de modificar y probar, habiendo hecho previamente una rama para tales fines, para no modificar master.

Si llegaran a necesitar modificar algún componente de Gemini, o precisaran algún componente nuevo que no exsita, por favor avisar a Bruno Sastre.

Flujo de trabajo

Se sugiere el siguiente flujo de trabajo para la creación de un nuevo componente:

1. Crear branch

Parado en master, hacer pull y crear una nueva branch, usando el nombre del componente (sin el prefijo):

✅new-kb
❌gx-ide-new-kb

2. Duplicar el 'starter template'

./src/_template.

3. Renombrar 'template'

Renombrar 'template' en todos los casos donde sea necesario, usando el nombre del nuevo componente. En algunos casos hay que usar el prefijo 'gx-ide-' y en otros no. Por favor, prestar atención.

• carpeta _template -> my-new-component
• carpeta _template/gx-ide-assets/template -> my-new-component/gx-ide-assets/my-new-component
• archivo template.tsx -> my-new-component
• nombre de tag gx-ide-template -> gx-ide-my-new-component
• nombre de class Template -> MyNewComponent

4.A Desarrollo del componente

Desarrollar el componente teniendo en cuenta el documento de buenas practicas

4.B Revisar traducciones

Revisar que todos los textos son traducibles.

4.C Tests

Este punto es necesario, pero opcional de momento, ya que en este momento, es mas importante desarrollar que hacer tests. Consultar este punto con German Azís.
Nota: Antes de hacer los tests, definir la base URL como '/build'. De lo contrario, van a aparecer errores porque no se van a encontrar los assets"

const page = await newE2EPage();
const head = await page.find("head");
head.innerHTML = '<base href="/build/" />';

4.D Revisar lista de buenas prácticas

La lista de buenas prácticas debe tenerse presente durante el desarrollo, pero no esta de mas verificarla luego.

5. Crear una página html

Crear una pagina en ./src/pages para probar, y eventualmente mostrar el nuevo componente. Para eso, duplicar ./src/pages/template.html y modificar en ella lo necesario.

6. Netlify

Subir la carpeta www a un proyecto en netlify. Si es una rama en la que estan trabajando ustedes, tienen que subirla a una cuenta propia. Luego de subir la rama main a netlify me encargo yo (Bruno).

7. Compartir URL

Compartir con los involucrados del proyecto, la URL de netlify del nuevo componente, y aguardar feedback. Ej.:

https://649414c3255641072f165111--fascinating-cactus-daaa46.netlify.app/pages/my-new-component.html

Nota: Se solicita no cambiar la url que netlify provee por defecto. No queremos que sea de fácil acceso.

8. Pull Request

Una vez aprobado hacer un pull request solicitando el review de Daniel Mariño

Consideraciones

• Tratar de nombrar las ramas siguiendo este patrón: component/new-kb (para un nuevo componente). fix/new-kb (si es para un fix de un componente que ya se paso a main). feature/new-kb (si es para una feature de un componente que ya se pasó a main). Usar el nombre que quieran si ninguna de las anteriores aplica. Solo tratar de usar nombres coherentes/descriptivos.
• Luego de hacer el merge a main, la rama se elimina automáticamente.

Readme StencilJs

Leer el readme que viene con StencilJs

Links de interés

• StencilJs: La biblioteca que usamos para el desarrollo de los componentes.
• Specs.: La documentación de las specs. de los componentes.
• Estado de los componentes
• StencilJs readme: El readme de StencilJs.
• Diseños en Figma: (Falta)