-
Notifications
You must be signed in to change notification settings - Fork 1
[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
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this 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
- How to use the Chameleon components with wrappers (case for React and NextJS):
https://github.com/genexuslabs/chameleon-controls-library?tab=readme-ov-file#react
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.
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"/> [Installation for Angular](./docs/installation-for-angular.md) | ||
- <img src="./docs/images/react.svg" alt="React isotype" width="16"/> [Installation for React](./docs/installation-for-react.md) | ||
- <img src="./docs/images/stencil.svg" alt="Stencil isotype" width="16"/> [Installation for Stencil](./docs/installation-for-stencil.md) | ||
- <img src="./docs/images/vite.svg" alt="Vite isotype" width="16"/> [Installation for Vite](./docs/installation-for-vite.md) |
There was a problem hiding this comment.
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.
## 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. | | ||
|
There was a problem hiding this comment.
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.
## 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. | |
- [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) |
There was a problem hiding this comment.
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.
- [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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this text necessary?
Mercury Design System |
|
||
Mercury Design System | ||
|
||
# <img src="./images/angular.svg" alt="Angular isotype" width="30" /> Installation for Angular |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
# <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 |
#### 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 }} | ||
``` |
There was a problem hiding this comment.
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
#### 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 }} | |
``` |
[mercury]
Partition readme by framework[mercury]
Partition readme by framework and improve documentation
@bsastregx I've removed the |
## 1. Installation | ||
|
||
```bash | ||
npm i @genexus/mercury | ||
``` |
There was a problem hiding this comment.
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
Changes in this PR:
Mercury
README.md
has been partitioned into several readmes, one per framework/library, in order to improve reading user experience.