Skip to content

[mercury] Partition readme by framework and improve documentation #583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

bsastregx
Copy link
Collaborator

Changes in this PR:

Mercury README.md has been partitioned into several readmes, one per framework/library, in order to improve reading user experience.

@bsastregx bsastregx added documentation Improvements or additions to documentation mercury Changes related to Mercury design system target: major This PR is targeted for the next major release labels May 27, 2025
@bsastregx bsastregx requested a review from ncamera May 27, 2025 13:00
Copy link
Collaborator

@ncamera ncamera left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Vite is just a build tool. In this case, we should refactor the "React" readme to explicitly state that the example is for React with Vite. Also, we should add a separated example for NextJS.

You can see those examples here:
https://github.com/genexuslabs/chameleon-integrations/tree/main/packages

Also, we should explain

Another things to include (less priority):

  • Why wrappers are mandatory for React <= 18.

  • Which framework versions does Chameleon support?

  • Which minimal version of TypeScript target requires Mercury/Chameleon (ES2022).

  • The compatibility table for Mercury and Chameleon in the main readme.

Comment on lines +17 to +22
Mercury provides clear installation steps for the most popular frameworks and libraries, including React, Angular, Stencil, and Vite, making it easy to get started no matter your setup. Click on the following links to view the installation steps for your specific framework:

## 4. CLI flags
- <img src="./docs/images/angular.svg" alt="Angular isotype" width="16"/>&nbsp; [Installation for Angular](./docs/installation-for-angular.md)
- <img src="./docs/images/react.svg" alt="React isotype" width="16"/>&nbsp; [Installation for React](./docs/installation-for-react.md)
- <img src="./docs/images/stencil.svg" alt="Stencil isotype" width="16"/>&nbsp; [Installation for Stencil](./docs/installation-for-stencil.md)
- <img src="./docs/images/vite.svg" alt="Vite isotype" width="16"/>&nbsp; [Installation for Vite](./docs/installation-for-vite.md)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Vite is not a framework, but a build tool. In this case, one entry should be for React with Vite and another one for NextJS.

Comment on lines +319 to +372
## 3. CSS bundles mapping

The CSS for the Mercury's implementation is split into bundles to give explicit control over the downloaded CSS and allow developers to optimize performance by only using the CSS needed for each page.

Each CSS bundle contains a set of classes to style the [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) components and traditional HTML elements. The classes defined for each bundle can be seen in the [showcase](https://mercury-showcase.genexus.com/).

The following table describes all CSS bundles.

| Bundle name | Content |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chameleon/scrollbar` | Styles for the scrollbar of the components |
| `components/accordion` | Styles for the [accordion](https://mercury-showcase.genexus.com/mercury/components/accordion) component |
| `components/button` | Styles for the [button](https://mercury-showcase.genexus.com/mercury/components/button) button |
| `components/chat` | Styles for the chat component |
| `components/checkbox` | Styles for the [checkbox](https://mercury-showcase.genexus.com/mercury/components/checkbox) component |
| `components/code` | Styles for the code block component |
| `components/combo-box` | Styles for the [combo-box](https://mercury-showcase.genexus.com/mercury/components/combo-box) component |
| `components/dialog` | Styles for the [dialog](https://mercury-showcase.genexus.com/mercury/components/dialog) component |
| `components/dropdown` | Styles for the dropdown component |
| `components/edit` | Styles for the [input](https://mercury-showcase.genexus.com/mercury/components/input) and [search](https://mercury-showcase.genexus.com/mercury/components/search) components |
| `components/flexible-layout` | Styles for the flexible layout component |
| `components/icon` | Styles for the [icon](https://mercury-showcase.genexus.com/mercury/components/icon) component |
| `components/layout-splitter` | Styles for the layout splitter component |
| `components/list-box` | Styles for the [list box](https://mercury-showcase.genexus.com/mercury/components/list-box) component |
| `components/markdown-viewer` | Styles for the markdown viewer component |
| `components/navigation-list` | Styles for the navigation list component |
| `components/pills` | Styles for the [pills](https://mercury-showcase.genexus.com/mercury/components/pills) component |
| `components/radio-group` | Styles for the [radio group](https://mercury-showcase.genexus.com/mercury/components/radio-group) component |
| `components/segmented-control` | Styles for the segmented control component |
| `components/sidebar` | Styles for the sidebar component |
| `components/slider` | Styles for the [slider](https://mercury-showcase.genexus.com/mercury/components/slider) component |
| `components/switch` | Styles for the switch component |
| `components/tab` | Styles for the [tab](https://mercury-showcase.genexus.com/mercury/components/tab) component |
| `components/tabular-grid` | Styles for the [tabular grid](https://mercury-showcase.genexus.com/mercury/components/tabular-grid) and [property grid](https://mercury-showcase.genexus.com/mercury/components/tabular-grid) components |
| `components/ticket-list` | Styles for the ticket list component |
| `components/tooltip` | Styles for the [tooltip](https://mercury-showcase.genexus.com/mercury/components/tooltip) component |
| `components/tree-view` | Styles for the [tree view](https://mercury-showcase.genexus.com/mercury/components/tree-view) component |
| `components/widget` | Styles for the [widget](https://mercury-showcase.genexus.com/mercury/components/widget) component |
| `utils/elevation` | Styles to apply [elevations](https://mercury-showcase.genexus.com/mercury/utility-classes/elevation) on any component |
| `utils/form` | Styles for the [label](https://mercury-showcase.genexus.com/mercury/components/label) component and to build layouts for [forms](https://mercury-showcase.genexus.com/mercury/utility-classes/form) |
| `utils/layout` | Styles to build common [layouts](https://mercury-showcase.genexus.com/mercury/utility-classes/layout) |
| `utils/spacing` | Styles to apply [spacing](https://mercury-showcase.genexus.com/mercury/utility-classes/spacing) in different components that are used as containers |
| `utils/typography` | Styles for using the different [typographies](https://mercury-showcase.genexus.com/mercury/utility-classes/typography) |

## 4. CLI flags

| Flag | Description |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--globant` <br/><br/> `--gl` <br/><br/> `-gl` | If specified, the generated CSS will use the tokens for the Mercury Globant variant. |
| `--icons-path=path` <br/><br/>`--icons=path` <br/><br/>`--i=path` <br/><br/>`-i=path` | Allows you to customize the base path for the icons. If not specified, `./assets/icons/` will be used. |
| `--font-face-path=path` <br/><br/>`--font-face=path` <br/><br/>`--f=path` <br/><br/>`-f=path` | Allows you to customize the base path for the custom fonts. If not specified, `./assets/fonts/` will be used. |
| `--avoid-hash=bundle1,bundle2,...` <br/><br/>`--ah=bundle1,bundle2,...` <br/><br/>`-ah=bundle1,bundle2,...` | Receives a set of comma-separated values, where each value is a bundle. Allows you to avoid the creating the hash for the provided bundles. |
| `--outDir=path` <br/><br/>`--outdir=path` <br/><br/>`--o=path` <br/><br/>`-o=path` | Allows you to customize the path where the CSS files will be created. If not specified, `./mercury/` will be used. |

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This information is duplicated in each subreadme. We should move this common docs to the main readme file.

Suggested change
## 3. CSS bundles mapping
The CSS for the Mercury's implementation is split into bundles to give explicit control over the downloaded CSS and allow developers to optimize performance by only using the CSS needed for each page.
Each CSS bundle contains a set of classes to style the [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) components and traditional HTML elements. The classes defined for each bundle can be seen in the [showcase](https://mercury-showcase.genexus.com/).
The following table describes all CSS bundles.
| Bundle name | Content |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chameleon/scrollbar` | Styles for the scrollbar of the components |
| `components/accordion` | Styles for the [accordion](https://mercury-showcase.genexus.com/mercury/components/accordion) component |
| `components/button` | Styles for the [button](https://mercury-showcase.genexus.com/mercury/components/button) button |
| `components/chat` | Styles for the chat component |
| `components/checkbox` | Styles for the [checkbox](https://mercury-showcase.genexus.com/mercury/components/checkbox) component |
| `components/code` | Styles for the code block component |
| `components/combo-box` | Styles for the [combo-box](https://mercury-showcase.genexus.com/mercury/components/combo-box) component |
| `components/dialog` | Styles for the [dialog](https://mercury-showcase.genexus.com/mercury/components/dialog) component |
| `components/dropdown` | Styles for the dropdown component |
| `components/edit` | Styles for the [input](https://mercury-showcase.genexus.com/mercury/components/input) and [search](https://mercury-showcase.genexus.com/mercury/components/search) components |
| `components/flexible-layout` | Styles for the flexible layout component |
| `components/icon` | Styles for the [icon](https://mercury-showcase.genexus.com/mercury/components/icon) component |
| `components/layout-splitter` | Styles for the layout splitter component |
| `components/list-box` | Styles for the [list box](https://mercury-showcase.genexus.com/mercury/components/list-box) component |
| `components/markdown-viewer` | Styles for the markdown viewer component |
| `components/navigation-list` | Styles for the navigation list component |
| `components/pills` | Styles for the [pills](https://mercury-showcase.genexus.com/mercury/components/pills) component |
| `components/radio-group` | Styles for the [radio group](https://mercury-showcase.genexus.com/mercury/components/radio-group) component |
| `components/segmented-control` | Styles for the segmented control component |
| `components/sidebar` | Styles for the sidebar component |
| `components/slider` | Styles for the [slider](https://mercury-showcase.genexus.com/mercury/components/slider) component |
| `components/switch` | Styles for the switch component |
| `components/tab` | Styles for the [tab](https://mercury-showcase.genexus.com/mercury/components/tab) component |
| `components/tabular-grid` | Styles for the [tabular grid](https://mercury-showcase.genexus.com/mercury/components/tabular-grid) and [property grid](https://mercury-showcase.genexus.com/mercury/components/tabular-grid) components |
| `components/ticket-list` | Styles for the ticket list component |
| `components/tooltip` | Styles for the [tooltip](https://mercury-showcase.genexus.com/mercury/components/tooltip) component |
| `components/tree-view` | Styles for the [tree view](https://mercury-showcase.genexus.com/mercury/components/tree-view) component |
| `components/widget` | Styles for the [widget](https://mercury-showcase.genexus.com/mercury/components/widget) component |
| `utils/elevation` | Styles to apply [elevations](https://mercury-showcase.genexus.com/mercury/utility-classes/elevation) on any component |
| `utils/form` | Styles for the [label](https://mercury-showcase.genexus.com/mercury/components/label) component and to build layouts for [forms](https://mercury-showcase.genexus.com/mercury/utility-classes/form) |
| `utils/layout` | Styles to build common [layouts](https://mercury-showcase.genexus.com/mercury/utility-classes/layout) |
| `utils/spacing` | Styles to apply [spacing](https://mercury-showcase.genexus.com/mercury/utility-classes/spacing) in different components that are used as containers |
| `utils/typography` | Styles for using the different [typographies](https://mercury-showcase.genexus.com/mercury/utility-classes/typography) |
## 4. CLI flags
| Flag | Description |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--globant` <br/><br/> `--gl` <br/><br/> `-gl` | If specified, the generated CSS will use the tokens for the Mercury Globant variant. |
| `--icons-path=path` <br/><br/>`--icons=path` <br/><br/>`--i=path` <br/><br/>`-i=path` | Allows you to customize the base path for the icons. If not specified, `./assets/icons/` will be used. |
| `--font-face-path=path` <br/><br/>`--font-face=path` <br/><br/>`--f=path` <br/><br/>`-f=path` | Allows you to customize the base path for the custom fonts. If not specified, `./assets/fonts/` will be used. |
| `--avoid-hash=bundle1,bundle2,...` <br/><br/>`--ah=bundle1,bundle2,...` <br/><br/>`-ah=bundle1,bundle2,...` | Receives a set of comma-separated values, where each value is a bundle. Allows you to avoid the creating the hash for the provided bundles. |
| `--outDir=path` <br/><br/>`--outdir=path` <br/><br/>`--o=path` <br/><br/>`-o=path` | Allows you to customize the path where the CSS files will be created. If not specified, `./mercury/` will be used. |

Comment on lines +21 to +23
- [2.3. Copy the CSS bundles, custom fonts and icons to the dev and prod builds](#23-copy-the-css-bundles-custom-fonts-and-icons-to-the-dev-and-prod-builds)

- [2.3.1. Copying assets](#231-copying-assets)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not necessary to create a sub-section if only one exists. Collapse the content of the 2.3 and 2.3.1.

The same reasoning applies to all occurrences of this pattern.

Suggested change
- [2.3. Copy the CSS bundles, custom fonts and icons to the dev and prod builds](#23-copy-the-css-bundles-custom-fonts-and-icons-to-the-dev-and-prod-builds)
- [2.3.1. Copying assets](#231-copying-assets)
- [2.3. Copy the CSS bundles, custom fonts and icons to the dev and prod builds](#23-copy-the-css-bundles-custom-fonts-and-icons-to-the-dev-and-prod-builds)

@@ -0,0 +1,372 @@
<img src="./images/mercury-brand.svg" alt="Mercury brand" width="30" />

Mercury Design System
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this text necessary?

Suggested change
Mercury Design System


Mercury Design System

# <img src="./images/angular.svg" alt="Angular isotype" width="30" /> Installation for Angular
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# <img src="./images/angular.svg" alt="Angular isotype" width="30" /> Installation for Angular
# <img src="./images/angular.svg" alt="Angular logo" width="30" /> Installation for Angular

Comment on lines +132 to +156
#### 2.2.2. Using SASS to transpile the CSS bundles

> [!WARNING]
> We don't recommend this way, because the CLI does this under the hood in a much better and faster way. Also, this way does not hash the generated CSS, which leads to cache issues when re-deploying your application after updating your version of Mercury.

1. Install `sass` dependency to transpile the bundles.

```bash
npm i -D sass
```

2. Add a config file (called `config.scss`) in your project to determine the path to the assets.
Include the following configuration:

```scss
$font-face-path: "{{ Fonts final path }}";
$icons-path: "{{ Icons final path }}";
$globant-colors: false;
```

3. Run the following command to transpile the bundles with the new path for the assets:

```bash
npx sass --load-path=<path to config.scss directory> --no-source-map --style compressed <path to node_modules>/@genexus/mercury/dist/bundles/scss:{{ CSS outDir path }}
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This option is no longer supported since the 0.21.0 version
https://github.com/genexuslabs/design-systems/releases/tag/v0.0.194

Suggested change
#### 2.2.2. Using SASS to transpile the CSS bundles
> [!WARNING]
> We don't recommend this way, because the CLI does this under the hood in a much better and faster way. Also, this way does not hash the generated CSS, which leads to cache issues when re-deploying your application after updating your version of Mercury.
1. Install `sass` dependency to transpile the bundles.
```bash
npm i -D sass
```
2. Add a config file (called `config.scss`) in your project to determine the path to the assets.
Include the following configuration:
```scss
$font-face-path: "{{ Fonts final path }}";
$icons-path: "{{ Icons final path }}";
$globant-colors: false;
```
3. Run the following command to transpile the bundles with the new path for the assets:
```bash
npx sass --load-path=<path to config.scss directory> --no-source-map --style compressed <path to node_modules>/@genexus/mercury/dist/bundles/scss:{{ CSS outDir path }}
```

@ncamera ncamera changed the title [mercury] Partition readme by framework [mercury] Partition readme by framework and improve documentation May 27, 2025
@ncamera ncamera added target: patch This PR is targeted for the next patch release and removed target: major This PR is targeted for the next major release labels May 27, 2025
@ncamera
Copy link
Collaborator

ncamera commented May 27, 2025

@bsastregx I've removed the target: major as this is not a breaking change. Once this PR is merged and versioned, the Mercury usage won't change.

Comment on lines +43 to +47
## 1. Installation

```bash
npm i @genexus/mercury
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can move this section to the main readme file. We should also explain how to install Chameleon too.

npm i --save @genexus/chameleon-controls-library @genexus/mercury

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation mercury Changes related to Mercury design system target: patch This PR is targeted for the next patch release
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants