@genexus/mercury 0.28.1 → 0.28.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -505
- package/dist/assets/MERCURY_ASSETS.ts +5306 -5306
- package/dist/assets-manager.d.ts +1 -1
- package/dist/bundles/css/all.css +1 -1
- package/dist/bundles/css/components/dialog.css +1 -1
- package/dist/cli/bundle.js +2 -4
- package/package.json +13 -5
package/README.md
CHANGED
|
@@ -1,547 +1,88 @@
|
|
|
1
|
-
# Mercury Design System
|
|
1
|
+
#  Mercury Design System
|
|
2
2
|
|
|
3
|
-
Mercury Design System is a robust and scalable solution designed to improve product development. It's implemented over [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) a library of white-label, highly-customizable and reusable web components, which implements all components
|
|
3
|
+
Mercury Design System is a robust and scalable solution designed to improve product development. It's implemented over [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) a library of white-label, highly-customizable and reusable web components, which implements all necessary components for the Mercury DS.
|
|
4
4
|
|
|
5
5
|
**Chameleon** works on every framework since it's a library of web components (the standard for creating components in the web) and provides the following features:
|
|
6
6
|
|
|
7
|
-
- It build with accessibility in mind.
|
|
7
|
+
- It's build with accessibility in mind.
|
|
8
8
|
- Tiny bundle size.
|
|
9
9
|
- Blazing fast performance.
|
|
10
10
|
- Full RTL and internationalization support.
|
|
11
11
|
- Open source.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
This repository provides the following assets:
|
|
14
14
|
|
|
15
|
-
- [
|
|
15
|
+
- Individual CSS modules to style each [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) component.
|
|
16
|
+
- Pre-packaged font assets (Inter family).
|
|
17
|
+
- Consistent icon set for UI/UX.
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
## 👟 Getting Started with Mercury
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
Mercury provides clear installation steps for the most popular frameworks and libraries, including React, Angular, and Stencil, making it easy to get started no matter your setup. First, install **Chameleon** and **Mercury**, and then click on the following links to view the installation steps for your specific framework:
|
|
20
22
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- [2.2.1. Using the CLI to create the CSS bundles](#221-using-the-cli-to-create-the-css-bundles)
|
|
24
|
-
|
|
25
|
-
- [2.2.2. Using SASS to transpile the CSS bundles](#222-using-sass-to-transpile-the-css-bundles)
|
|
26
|
-
|
|
27
|
-
- [2.2.3. Using already generated CSS bundles](#223-using-already-generated-css-bundles)
|
|
28
|
-
|
|
29
|
-
- [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)
|
|
30
|
-
|
|
31
|
-
- [2.3.1. Copying assets with Angular](#231-copying-assets-with-angular)
|
|
32
|
-
|
|
33
|
-
- [2.3.2. Copying assets with NextJS](#232-copying-assets-with-nextjs)
|
|
34
|
-
|
|
35
|
-
- [2.3.3. Copying assets with StencilJS](#233-copying-assets-with-stenciljs)
|
|
36
|
-
|
|
37
|
-
- [2.3.4. Copying assets with Vite](#234-copying-assets-with-vite)
|
|
38
|
-
|
|
39
|
-
- [2.4. Register Mercury and Chameleon utilities](#24-register-mercury-and-chameleon-utilities)
|
|
40
|
-
|
|
41
|
-
- [2.5. Style the base application](#25-style-the-base-application)
|
|
42
|
-
|
|
43
|
-
- [2.5.1. Adding base styles using Vite](#251-adding-base-styles-using-vite)
|
|
44
|
-
|
|
45
|
-
- [2.5.2. Adding base styles using React](#252-adding-base-styles-using-react)
|
|
46
|
-
|
|
47
|
-
- [2.5.3. Adding base styles using normal HTML](#253-adding-base-styles-using-normal-html)
|
|
48
|
-
|
|
49
|
-
- [2.6. Style the components with the CSS bundles](#26-style-the-components-with-the-css-bundles)
|
|
50
|
-
|
|
51
|
-
- [2.6.1 How to style a component in Angular](#261-how-to-style-a-component-in-angular)
|
|
52
|
-
|
|
53
|
-
- [2.6.2. How to style a component in React](#262-how-to-style-a-component-in-react)
|
|
54
|
-
|
|
55
|
-
- [2.6.3. How to style a component in StencilJS](#263-how-to-style-a-component-in-stenciljs)
|
|
56
|
-
|
|
57
|
-
- [2.7. Download the icon paths](#27-download-the-icon-paths)
|
|
58
|
-
|
|
59
|
-
- [2.8. Set the dark and light mode](#28-set-the-darklight-mode)
|
|
60
|
-
|
|
61
|
-
- [3. CSS bundles mapping](#3-css-bundles-mapping)
|
|
62
|
-
|
|
63
|
-
- [4. CLI flags](#4-cli-flags)
|
|
64
|
-
|
|
65
|
-
## 1. Installation
|
|
23
|
+
`npm`
|
|
66
24
|
|
|
67
25
|
```bash
|
|
68
|
-
npm i @genexus/mercury
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## 2. Usage
|
|
72
|
-
|
|
73
|
-
This repository provides the following assets to implement the Mercury DS:
|
|
74
|
-
|
|
75
|
-
- CSS to style the [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) components.
|
|
76
|
-
- Custom fonts.
|
|
77
|
-
- Icons.
|
|
78
|
-
|
|
79
|
-
The CSS is divided by bundles, where each bundle contains the CSS to style a component. For example, to style a `button` we have the `components/button` bundle, to style the `ch-checkbox` we have the `components/checkbox`, and so on.
|
|
80
|
-
|
|
81
|
-
Check out to the [CSS bundles mapping](#3-css-bundles-mapping) section to see how each component in the Mercury DS Figma maps to a CSS bundle. This mapping is also present on every page of [showcase](https://mercury-showcase.genexus.com/).
|
|
82
|
-
|
|
83
|
-
### 2.1. Before starting, define the path for the CSS bundles, custom fonts and icons
|
|
84
|
-
|
|
85
|
-
First of all, you must define the path where the CSS bundles, custom fonts, and icons will be contained in the `dist` folder of your final application.
|
|
86
|
-
|
|
87
|
-
We will refer to those paths with the following names:
|
|
88
|
-
|
|
89
|
-
| Reference | Meaning | Example |
|
|
90
|
-
| ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------- |
|
|
91
|
-
| `{{ CSS outDir path }}` | An untracked folder for generating the CSS of the application. | `/src/assets/mercury-css/` |
|
|
92
|
-
| `{{ CSS bundles final path }}` | Path in the final application (`dist` folder) where the CSS bundles will be consumed. | `/assets/css/` |
|
|
93
|
-
| `{{ Fonts final path }}` | Path in the final application (`dist` folder) where the custom fonts will be consumed. | `/assets/fonts/` |
|
|
94
|
-
| `{{ Icons final path }}` | Path in the final application (`dist` folder) where the icons will be consumed. | `/assets/icons/` |
|
|
95
|
-
|
|
96
|
-
### 2.2. Create the CSS bundles
|
|
97
|
-
|
|
98
|
-
After you have defined the path for assets, you must create the CSS bundles with the path to those assets.
|
|
99
|
-
|
|
100
|
-
In the following sections we provide examples of how to create those CSS bundles.
|
|
101
|
-
|
|
102
|
-
#### 2.2.1. Using the CLI to create the CSS bundles
|
|
103
|
-
|
|
104
|
-
> [!IMPORTANT]
|
|
105
|
-
> This is the way we recommend to create the bundles.
|
|
106
|
-
|
|
107
|
-
Mercury exposes a CLI to automate the creation of bundles. This CLI comes with the installation of the `@genexus/mercury` dependency.
|
|
108
|
-
|
|
109
|
-
Usage:
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
# Command line
|
|
113
|
-
npx mercury <flags>
|
|
114
|
-
|
|
115
|
-
# package.json script
|
|
116
|
-
"build.scss": "mercury <flags>"
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
Consult the [CLI flags](#4-cli-flags) section to read the complete documentation for the CLI.
|
|
120
|
-
|
|
121
|
-
Using the CLI:
|
|
122
|
-
|
|
123
|
-
1. Add a `"build.scss"` script in your package.json and include the paths where the icons and fonts will be copied, also include the `outDir` path where the CSS will be generated.
|
|
124
|
-
|
|
125
|
-
For example:
|
|
126
|
-
|
|
127
|
-
```json
|
|
128
|
-
"build.scss": "mercury --i={{ Icons final path }} --f={{ Fonts path final }} --outDir={{ CSS outDir path }}"
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
2. Use the `"build.scss"` script before building your application (dev server and prod build).
|
|
132
|
-
|
|
133
|
-
For example:
|
|
134
|
-
|
|
135
|
-
```json
|
|
136
|
-
"dev": "npm run build.scss && ...",
|
|
137
|
-
"start": "npm run build.scss && ...",
|
|
138
|
-
"build": "npm run build.scss && ..."
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
3. Before using any Mercury or [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) utility, you must register the bundle mapping. This mapping allows Mercury to map the bundle names with the real name of the CSS file (for example, `bundleToHashMappings["components/button"] --> components/button-9f82641938b85445`).
|
|
142
|
-
|
|
143
|
-
**IMPORTANT**: Run this JavaScript before using any Mercury or [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) utilities.
|
|
144
|
-
|
|
145
|
-
```ts
|
|
146
|
-
import { setBundleMapping } from "@genexus/mercury/dist/bundles";
|
|
147
|
-
import { bundleToHashMappings } from "{{ CSS outDir path }}/bundle-to-hash-mappings";
|
|
148
|
-
|
|
149
|
-
setBundleMapping(bundleToHashMappings);
|
|
150
|
-
|
|
151
|
-
// Other Mercury and Chameleon utilities...
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
#### 2.2.2. Using SASS to transpile the CSS bundles
|
|
155
|
-
|
|
156
|
-
> [!WARNING]
|
|
157
|
-
> 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.
|
|
158
|
-
|
|
159
|
-
1. Install `sass` dependency to transpile the bundles.
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
npm i -D sass
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
2. Add a config file (called `config.scss`) in your project to determine the path to the assets.
|
|
166
|
-
Include the following configuration:
|
|
167
|
-
|
|
168
|
-
```scss
|
|
169
|
-
$font-face-path: "{{ Fonts final path }}";
|
|
170
|
-
$icons-path: "{{ Icons final path }}";
|
|
171
|
-
$globant-colors: false;
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
3. Run the following command to transpile the bundles with the new path for the assets:
|
|
175
|
-
|
|
176
|
-
```bash
|
|
177
|
-
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 }}
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
#### 2.2.3. Using already generated CSS bundles
|
|
181
|
-
|
|
182
|
-
> [!WARNING]
|
|
183
|
-
> We don't recommend this way, because the generated CSS contains fixed paths for the assets and the CSS names don't contain a hash, which leads to cache issues when re-deploying your application after updating your version of Mercury.
|
|
184
|
-
> We only include this case, because in some scenarios it can facilitate the initialization with Mercury.
|
|
185
|
-
|
|
186
|
-
1. Copy the `<path to node_modules>/@genexus/mercury/dist/bundles/css` content to the `{{ CSS outDir path }}` where the CSS will be.
|
|
187
|
-
|
|
188
|
-
### 2.3. Copy the CSS bundles, custom fonts and icons to the dev and prod builds
|
|
189
|
-
|
|
190
|
-
Custom fonts and icons are distributed under the following folders:
|
|
191
|
-
|
|
192
|
-
- `<path to node_modules>/@genexus/mercury/dist/assets/fonts`
|
|
193
|
-
- `<path to node_modules>/@genexus/mercury/dist/assets/icons`
|
|
194
|
-
|
|
195
|
-
To use these assets with the CSS bundles, we recommend copying them statically, that is, do not track these assets in your repository sources, only copy them to the dev server and prod builds.
|
|
196
|
-
|
|
197
|
-
In the following sections we provide examples of how to copy the assets with different build tools and frameworks.
|
|
198
|
-
|
|
199
|
-
#### 2.3.1. Copying assets with Angular
|
|
200
|
-
|
|
201
|
-
```json
|
|
202
|
-
{
|
|
203
|
-
"projects": {
|
|
204
|
-
"<app name>": {
|
|
205
|
-
"architect": {
|
|
206
|
-
"build": {
|
|
207
|
-
"options": {
|
|
208
|
-
"assets": [
|
|
209
|
-
{
|
|
210
|
-
"glob": "**/*",
|
|
211
|
-
"input": "{{ CSS outDir path }}",
|
|
212
|
-
"output": "{{ CSS bundles final path }}"
|
|
213
|
-
},
|
|
214
|
-
{
|
|
215
|
-
"glob": "**/*",
|
|
216
|
-
"input": "<path to node_modules>/@genexus/mercury/dist/assets/fonts",
|
|
217
|
-
"output": "{{ Fonts final path }}"
|
|
218
|
-
},
|
|
219
|
-
{
|
|
220
|
-
"glob": "**/*",
|
|
221
|
-
"input": "<path to node_modules>/@genexus/mercury/dist/assets/icons",
|
|
222
|
-
"output": "{{ Icons final path }}"
|
|
223
|
-
}
|
|
224
|
-
]
|
|
225
|
-
}
|
|
226
|
-
}
|
|
227
|
-
}
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
}
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
#### 2.3.2. Copying assets with NextJS
|
|
234
|
-
|
|
235
|
-
First, install `copy-webpack-plugin`:
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
npm i copy-webpack-plugin --save-dev
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
```ts
|
|
242
|
-
// next.config.ts
|
|
243
|
-
import type { NextConfig } from "next";
|
|
244
|
-
import CopyWebpackPlugin from "copy-webpack-plugin";
|
|
245
|
-
|
|
246
|
-
const nextConfig: NextConfig = {
|
|
247
|
-
webpack: (config, { isServer }) => {
|
|
248
|
-
// Only apply the plugin for client-side builds
|
|
249
|
-
if (!isServer) {
|
|
250
|
-
config.plugins.push(
|
|
251
|
-
new CopyWebpackPlugin({
|
|
252
|
-
patterns: [
|
|
253
|
-
{
|
|
254
|
-
from: "{{ CSS outDir path }}",
|
|
255
|
-
to: "{{ CSS bundles final path }}"
|
|
256
|
-
},
|
|
257
|
-
{
|
|
258
|
-
from: "<path to node_modules>/@genexus/mercury/dist/assets/fonts",
|
|
259
|
-
to: "{{ Fonts final path }}"
|
|
260
|
-
},
|
|
261
|
-
{
|
|
262
|
-
from: "<path to node_modules>/@genexus/mercury/dist/assets/icons",
|
|
263
|
-
to: "{{ Icons final path }}"
|
|
264
|
-
}
|
|
265
|
-
]
|
|
266
|
-
})
|
|
267
|
-
);
|
|
268
|
-
}
|
|
269
|
-
|
|
270
|
-
return config;
|
|
271
|
-
}
|
|
272
|
-
};
|
|
273
|
-
|
|
274
|
-
export default nextConfig;
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
#### 2.3.3. Copying assets with StencilJS
|
|
278
|
-
|
|
279
|
-
When building web components with the StencilJS compiler, the assets can be copied using the copy tasks that provides StencilJS:
|
|
280
|
-
|
|
281
|
-
```ts
|
|
282
|
-
// stencil.config.ts
|
|
283
|
-
import { Config } from "@stencil/core";
|
|
284
|
-
import { CopyTask } from "@stencil/core/internal";
|
|
285
|
-
|
|
286
|
-
const copyTasks = [
|
|
287
|
-
{
|
|
288
|
-
src: "{{ CSS outDir path }}",
|
|
289
|
-
dest: "{{ CSS bundles final path }}"
|
|
290
|
-
},
|
|
291
|
-
{
|
|
292
|
-
src: "<path to node_modules>/@genexus/mercury/dist/assets/fonts",
|
|
293
|
-
dest: "{{ Fonts final path }}"
|
|
294
|
-
},
|
|
295
|
-
{
|
|
296
|
-
src: "<path to node_modules>/@genexus/mercury/dist/assets/icons",
|
|
297
|
-
dest: "{{ Icons final path }}"
|
|
298
|
-
}
|
|
299
|
-
] as const satisfies CopyTask[];
|
|
300
|
-
|
|
301
|
-
export const config: Config = {
|
|
302
|
-
namespace: "your-name-space",
|
|
303
|
-
outputTargets: [
|
|
304
|
-
{
|
|
305
|
-
type: "dist",
|
|
306
|
-
copy: copyTasks
|
|
307
|
-
},
|
|
308
|
-
{
|
|
309
|
-
type: "www",
|
|
310
|
-
serviceWorker: null,
|
|
311
|
-
copy: copyTasks
|
|
312
|
-
}
|
|
313
|
-
]
|
|
314
|
-
};
|
|
26
|
+
npm i --save @genexus/chameleon-controls-library @genexus/mercury
|
|
315
27
|
```
|
|
316
28
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
First, install `vite-plugin-static-copy`:
|
|
29
|
+
`yarn`
|
|
320
30
|
|
|
321
31
|
```bash
|
|
322
|
-
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
```ts
|
|
326
|
-
// vite.config.ts
|
|
327
|
-
import { defineConfig } from "vite";
|
|
328
|
-
import { viteStaticCopy } from "vite-plugin-static-copy";
|
|
329
|
-
|
|
330
|
-
export default defineConfig({
|
|
331
|
-
plugins: [
|
|
332
|
-
viteStaticCopy({
|
|
333
|
-
targets: [
|
|
334
|
-
{
|
|
335
|
-
src: "{{ CSS outDir path }}",
|
|
336
|
-
dest: "{{ CSS bundles final path }}"
|
|
337
|
-
},
|
|
338
|
-
{
|
|
339
|
-
src: "<path to node_modules>/@genexus/mercury/dist/assets/fonts",
|
|
340
|
-
dest: "{{ Fonts final path }}"
|
|
341
|
-
},
|
|
342
|
-
{
|
|
343
|
-
src: "<path to node_modules>/@genexus/mercury/dist/assets/icons",
|
|
344
|
-
dest: "{{ Icons final path }}"
|
|
345
|
-
}
|
|
346
|
-
]
|
|
347
|
-
})
|
|
348
|
-
]
|
|
349
|
-
});
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
### 2.4. Register Mercury and Chameleon utilities
|
|
353
|
-
|
|
354
|
-
[Chameleon](https://github.com/genexuslabs/chameleon-controls-library) and Mercury export utilities to facilitate the usage of icons. If you are using Mercury icons, do the following:
|
|
355
|
-
|
|
356
|
-
```ts
|
|
357
|
-
import { registryProperty } from "@genexus/chameleon-controls-library/dist/collection";
|
|
358
|
-
import { getImagePathCallbackDefinitions } from "@genexus/mercury/assets-manager.js";
|
|
359
|
-
import { registerMercury } from "@genexus/mercury/register-mercury.js";
|
|
360
|
-
|
|
361
|
-
// Register the default value for the getImagePathCallback property in all Chameleon
|
|
362
|
-
// components. This implementation allows us to remove the need for binding the
|
|
363
|
-
// getImagePathCallback property in all Chameleon controls that must render icons.
|
|
364
|
-
registryProperty("getImagePathCallback", getImagePathCallbackDefinitions);
|
|
365
|
-
|
|
366
|
-
// It registers a mapping between the icons metadata and its path.
|
|
367
|
-
registerMercury();
|
|
32
|
+
yarn add @genexus/chameleon-controls-library @genexus/mercury
|
|
368
33
|
```
|
|
369
34
|
|
|
370
|
-
|
|
35
|
+
Then follow the installation guide for your selected framework/library:
|
|
371
36
|
|
|
372
|
-
|
|
373
|
-
|
|
37
|
+
- <img src="./docs/images/angular.svg" alt="Angular isotype" width="16"/> [Installation for Angular](./docs/installation-for-angular.md)
|
|
38
|
+
- <img src="./docs/images/react.svg" alt="React isotype" width="16"/> [Installation for React (with Vite)](./docs/installation-for-react.md)
|
|
39
|
+
- <img src="./docs/images/nextjs.svg" alt="NextJs isotype" width="16"/> [Installation for Next.js](./docs/installation-for-next-js.md)
|
|
40
|
+
- <img src="./docs/images/stencil.svg" alt="Stencil isotype" width="16"/> [Installation for Stencil](./docs/installation-for-stencil.md)
|
|
374
41
|
|
|
375
|
-
|
|
42
|
+
---
|
|
376
43
|
|
|
377
|
-
|
|
44
|
+
> [NOTE]
|
|
45
|
+
> The following information is best read **after** completing any of the installation guides above.
|
|
378
46
|
|
|
379
|
-
|
|
380
|
-
> If the CSS bundles were created using the CLI, we recommend adding the `--avoid-hash=base/base` to avoid hashing the base CSS bundle and thus make the path to the base CSS bundle simpler.
|
|
47
|
+
## 🎨 One CSS module per Component
|
|
381
48
|
|
|
382
|
-
|
|
383
|
-
<!DOCTYPE html>
|
|
384
|
-
<html lang="en" dir="ltr">
|
|
385
|
-
<head>
|
|
386
|
-
<style>
|
|
387
|
-
@import "{{ CSS outDir path }}/base/base.css";
|
|
388
|
-
</style>
|
|
389
|
-
</head>
|
|
390
|
-
<body></body>
|
|
391
|
-
</html>
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
#### 2.5.2. Adding base styles using React
|
|
395
|
-
|
|
396
|
-
> [!TIP]
|
|
397
|
-
> If the CSS bundles were created using the CLI, we recommend adding the `--avoid-hash=base/base` to avoid hashing the base CSS bundle and thus make the path to the base CSS bundle simpler.
|
|
398
|
-
|
|
399
|
-
```ts
|
|
400
|
-
// App.tsx
|
|
401
|
-
import "{{ CSS outDir path }}/base/base.css";
|
|
402
|
-
```
|
|
49
|
+
The CSS in Mercury's implementation is divided into separate _modules_ of CSS (also called _bundles_). Each CSS module contains the specific styles needed to properly render an individual component or control. This approach ensures that each component has its required styling isolated and encapsulated.
|
|
403
50
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
```html
|
|
407
|
-
<!DOCTYPE html>
|
|
408
|
-
<html lang="en" dir="ltr">
|
|
409
|
-
<head>
|
|
410
|
-
<link
|
|
411
|
-
rel="stylesheet"
|
|
412
|
-
crossorigin
|
|
413
|
-
href="{{ CSS bundles final path }}/base/base-<hash>.css"
|
|
414
|
-
/>
|
|
415
|
-
</head>
|
|
416
|
-
<body></body>
|
|
417
|
-
</html>
|
|
418
|
-
```
|
|
51
|
+
### Why one CSS per component?
|
|
419
52
|
|
|
420
|
-
|
|
53
|
+
Loading one CSS file per component helps **limit the amount of CSS included**, leading to **faster page loads and better performance**. Instead of forcing the browser to process a massive, monolithic stylesheet with styles for components that may not even be used, each page or feature can load only the styles it actually requires. This results in **leaner CSS, faster rendering, and more maintainable code** in the long run.
|
|
421
54
|
|
|
422
|
-
|
|
55
|
+
### How do I import a CSS module?
|
|
423
56
|
|
|
424
|
-
|
|
57
|
+
To load the necessary CSS bundles, import the `getBundles` utility from Mercury. Use it to specify the bundles you need and assign the result to a variable. This variable is then passed to the `<ch-theme>` component, which handles applying the styles automatically.
|
|
425
58
|
|
|
426
|
-
|
|
59
|
+
The following snippet provides a quick, partial example using Angular, meant only to give you a sense of how it works. The approach is analogous across other frameworks. For complete installation and usage details, be sure to consult the full README for your specific framework by searching for `import { getBundles }`.
|
|
427
60
|
|
|
428
61
|
```ts
|
|
429
|
-
|
|
430
|
-
ChangeDetectionStrategy,
|
|
431
|
-
Component,
|
|
432
|
-
CUSTOM_ELEMENTS_SCHEMA
|
|
433
|
-
} from "@angular/core";
|
|
62
|
+
// ...non-essential imports for this example omitted
|
|
434
63
|
import { getBundles } from "@genexus/mercury/bundles.js";
|
|
435
64
|
|
|
436
65
|
@Component({
|
|
437
|
-
selector: "
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
66
|
+
selector: "my-own-component",
|
|
67
|
+
// ...non-essential code for this example omitted
|
|
68
|
+
template: `<ch-theme [model]="bundles"></ch-theme>
|
|
69
|
+
<div class="field field-block">
|
|
70
|
+
<label class="label" for="name">Phone</label>
|
|
71
|
+
<ch-edit class="input" id="phone" />
|
|
72
|
+
</div>
|
|
73
|
+
<button class="button-primary" type="button">Save Changes</button>`
|
|
443
74
|
})
|
|
444
75
|
export class CustomDialogComponent {
|
|
445
|
-
bundles = getBundles(
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
#### 2.6.2. How to style a component in React
|
|
450
|
-
|
|
451
|
-
```tsx
|
|
452
|
-
import { ChTheme } from "<path to Chameleon web components wrappers>";
|
|
453
|
-
import { getBundles } from "@genexus/mercury/bundles.js";
|
|
454
|
-
|
|
455
|
-
const bundles = getBundles("components/button", "{{ CSS bundles final path }}");
|
|
456
|
-
|
|
457
|
-
const CustomDialog = () => {
|
|
458
|
-
return (
|
|
459
|
-
<>
|
|
460
|
-
<ChTheme model={bundles}></ChTheme>
|
|
461
|
-
<button className="button-primary" type="button">
|
|
462
|
-
Caption
|
|
463
|
-
</button>
|
|
464
|
-
</>
|
|
76
|
+
bundles = getBundles(
|
|
77
|
+
["components/button", "components/edit", "utils/form"],
|
|
78
|
+
"{{ CSS bundles final path }}"
|
|
465
79
|
);
|
|
466
|
-
};
|
|
467
|
-
|
|
468
|
-
export default CustomDialog;
|
|
469
|
-
```
|
|
470
|
-
|
|
471
|
-
#### 2.6.3. How to style a component in StencilJS
|
|
472
|
-
|
|
473
|
-
```tsx
|
|
474
|
-
import { Component, Host } from "@stencil/core";
|
|
475
|
-
import { getBundles } from "@genexus/mercury/bundles.js";
|
|
476
|
-
|
|
477
|
-
const bundles = getBundles("components/button", "{{ CSS bundles final path }}");
|
|
478
|
-
|
|
479
|
-
@Component({
|
|
480
|
-
shadow: true,
|
|
481
|
-
styleUrl: "custom-dialog.scss",
|
|
482
|
-
tag: "custom-dialog"
|
|
483
|
-
})
|
|
484
|
-
export class CustomDialog {
|
|
485
|
-
render() {
|
|
486
|
-
return (
|
|
487
|
-
<Host>
|
|
488
|
-
<ch-theme model={bundles}></ch-theme>
|
|
489
|
-
<button class="button-primary" type="button">
|
|
490
|
-
Caption
|
|
491
|
-
</button>
|
|
492
|
-
</Host>
|
|
493
|
-
);
|
|
494
|
-
}
|
|
495
80
|
}
|
|
496
81
|
```
|
|
497
82
|
|
|
498
|
-
###
|
|
499
|
-
|
|
500
|
-
In the [Register Mercury and Chameleon utilities](#24-register-mercury-and-chameleon-utilities) section we registered utilities to compute the icons in the component. The only remaining thing to do is download the path for the icons. To do this, we need to download a CSS bundle called `base/icons` using the `ch-theme` component.
|
|
501
|
-
|
|
502
|
-
The only difference with the previous sections, is that the bundle is not downloaded using the getBundles utils, instead is computed with the following way:
|
|
503
|
-
|
|
504
|
-
```ts
|
|
505
|
-
import type { ThemeModel } from "@genexus/chameleon-controls-library";
|
|
506
|
-
import { bundleToHashMappings } from "{{ CSS outDir path }}/bundle-to-hash-mappings";
|
|
507
|
-
|
|
508
|
-
const iconsBundle: ThemeModel = [
|
|
509
|
-
{
|
|
510
|
-
name: "base/icons",
|
|
511
|
-
url: `{{ Icons final path }}${bundleToHashMappings["base/icons"]}.css`
|
|
512
|
-
}
|
|
513
|
-
];
|
|
514
|
-
|
|
515
|
-
// Use the iconsBundle in the ch-theme/ChTheme component...
|
|
516
|
-
```
|
|
517
|
-
|
|
518
|
-
### 2.8. Set the dark/light mode
|
|
83
|
+
### CSS bundles reference:
|
|
519
84
|
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
```html
|
|
523
|
-
// index.html (dark)
|
|
524
|
-
<!DOCTYPE html>
|
|
525
|
-
<html lang="en" dir="ltr" class="dark">
|
|
526
|
-
<head></head>
|
|
527
|
-
<body></body>
|
|
528
|
-
</html>
|
|
529
|
-
|
|
530
|
-
// index.html (light)
|
|
531
|
-
<!DOCTYPE html>
|
|
532
|
-
<html lang="en" dir="ltr" class="light">
|
|
533
|
-
<head></head>
|
|
534
|
-
<body></body>
|
|
535
|
-
</html>
|
|
536
|
-
```
|
|
537
|
-
|
|
538
|
-
## 3. CSS bundles mapping
|
|
539
|
-
|
|
540
|
-
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.
|
|
541
|
-
|
|
542
|
-
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/).
|
|
543
|
-
|
|
544
|
-
The following table describes all CSS bundles.
|
|
85
|
+
The reference below documents all Mercury CSS bundles. The “Bundle name” is the value you pass to `getBundles` to load the corresponding CSS module. For a clearer understanding, check out any component example [on the Mercury showcase](https://mercury-showcase.genexus.com/mercury/components/accordion).
|
|
545
86
|
|
|
546
87
|
| Bundle name | Content |
|
|
547
88
|
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -553,7 +94,7 @@ The following table describes all CSS bundles.
|
|
|
553
94
|
| `components/code` | Styles for the code block component |
|
|
554
95
|
| `components/combo-box` | Styles for the [combo-box](https://mercury-showcase.genexus.com/mercury/components/combo-box) component |
|
|
555
96
|
| `components/dialog` | Styles for the [dialog](https://mercury-showcase.genexus.com/mercury/components/dialog) component |
|
|
556
|
-
| `components/dropdown` | Styles for the dropdown component
|
|
97
|
+
| `components/dropdown` | Styles for the [dropdown](https://mercury-showcase.genexus.com/mercury/components/dropdown) component |
|
|
557
98
|
| `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 |
|
|
558
99
|
| `components/flexible-layout` | Styles for the flexible layout component |
|
|
559
100
|
| `components/icon` | Styles for the [icon](https://mercury-showcase.genexus.com/mercury/components/icon) component |
|
|
@@ -563,10 +104,10 @@ The following table describes all CSS bundles.
|
|
|
563
104
|
| `components/navigation-list` | Styles for the navigation list component |
|
|
564
105
|
| `components/pills` | Styles for the [pills](https://mercury-showcase.genexus.com/mercury/components/pills) component |
|
|
565
106
|
| `components/radio-group` | Styles for the [radio group](https://mercury-showcase.genexus.com/mercury/components/radio-group) component |
|
|
566
|
-
| `components/segmented-control` | Styles for the segmented control component
|
|
107
|
+
| `components/segmented-control` | Styles for the [segmented control](https://mercury-showcase.genexus.com/mercury/components/segmented-control) component |
|
|
567
108
|
| `components/sidebar` | Styles for the sidebar component |
|
|
568
109
|
| `components/slider` | Styles for the [slider](https://mercury-showcase.genexus.com/mercury/components/slider) component |
|
|
569
|
-
| `components/switch` | Styles for the switch component
|
|
110
|
+
| `components/switch` | Styles for the [switch](https://mercury-showcase.genexus.com/mercury/components/switch) component |
|
|
570
111
|
| `components/tab` | Styles for the [tab](https://mercury-showcase.genexus.com/mercury/components/tab) component |
|
|
571
112
|
| `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 |
|
|
572
113
|
| `components/ticket-list` | Styles for the ticket list component |
|
|
@@ -579,7 +120,24 @@ The following table describes all CSS bundles.
|
|
|
579
120
|
| `utils/spacing` | Styles to apply [spacing](https://mercury-showcase.genexus.com/mercury/utility-classes/spacing) in different components that are used as containers |
|
|
580
121
|
| `utils/typography` | Styles for using the different [typographies](https://mercury-showcase.genexus.com/mercury/utility-classes/typography) |
|
|
581
122
|
|
|
582
|
-
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## ⚙️ CLI flags
|
|
126
|
+
|
|
127
|
+
The following are the command-line parameters expected by the `mercury` CLI in your `package.json` script. This command generates the necessary assets for the Mercury Design System.
|
|
128
|
+
|
|
129
|
+
In example:
|
|
130
|
+
|
|
131
|
+
`package.json`
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
"scripts": {
|
|
135
|
+
// your other scripts...
|
|
136
|
+
"build.css": "mercury --i={{ Icons final path }} --f={{ Fonts path final }} --outDir={{ CSS outDir path }}"
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
(For complete installation and usage details, be sure to consult the full README for your specific framework)
|
|
583
141
|
|
|
584
142
|
| Flag | Description |
|
|
585
143
|
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -588,3 +146,58 @@ The following table describes all CSS bundles.
|
|
|
588
146
|
| `--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. |
|
|
589
147
|
| `--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. |
|
|
590
148
|
| `--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. |
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## ⚠️ Common issues
|
|
153
|
+
|
|
154
|
+
The following are some common issues and their solutions you might encounter during installation:
|
|
155
|
+
|
|
156
|
+
### # Missing Type Declarations in External Dependencies
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
Error: ../../node_modules/livekit-client/dist/src/room/PCTransport.d.ts:1:30
|
|
160
|
+
error TS7016: Could not find a declaration file for module 'events'.
|
|
161
|
+
/genexus/mercury-monorepo/node_modules/events/events.js' implicitly has an 'any' type.
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Add `skipLibCheck: true` to your `tsconfig.json`
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"compilerOptions": {
|
|
169
|
+
"skipLibCheck": true
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
<details>
|
|
175
|
+
<summary>Explanation</summary>
|
|
176
|
+
This error occurs when TypeScript cannot find type declarations for a module used by a third-party package. In this case, the `events` module is used by `livekit-client`, but no corresponding `.d.ts` file is found. A common workaround is to set `"skipLibCheck": true` in `tsconfig.json`, which disables type checking of declaration files in `node_modules`, allowing compilation to proceed despite the missing types.
|
|
177
|
+
</details>
|
|
178
|
+
|
|
179
|
+
### # Missing Export Error: 'OverlayEventDetail' Not Found in interfaces.ts (React only)
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
Uncaught SyntaxError: The requested module '/src/chameleon-components/react-component-lib/interfaces.ts?t=1752010434529' does not provide an export named 'OverlayEventDetail' (at createOverlayComponent.tsx:4:10)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Update the Stencil-generated files so that the types are imported with `type`.
|
|
186
|
+
|
|
187
|
+
before
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
import { OverlayEventDetail } from "./interfaces";
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
after
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
import { type OverlayEventDetail } from "./interfaces";
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
<details>
|
|
200
|
+
<summary>Explanation</summary>
|
|
201
|
+
This is a temporary issue affecting Chameleon integration in React projects. React requires wrappers for custom elements, and starting from Chameleon v6.4.0, a CLI is available to generate them using Stencil. However, the Stencil-generated files omit the `type` keyword when a type is imported. If your `tsconfig.json` has `verbatimModuleSyntax: true`, this will cause an import error.
|
|
202
|
+
</details>
|
|
203
|
+
|