npm package: @genexus/mercury
Description: Mercury Design System is a robust and scalable solution designed to improve product development.
Latest version: 1.2.1

# ![Mercury brand](./docs/images/mercury-brand.svg) Mercury Design System

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.

**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:

- It's build with accessibility in mind.
- Tiny bundle size.
- Blazing fast performance.
- Full RTL and internationalization support.
- Open source.

This repository provides the following assets:

- Individual CSS modules to style each [Chameleon](https://github.com/genexuslabs/chameleon-controls-library) component.
- Pre-packaged font assets (Inter family).
- Consistent icon set for UI/UX.

## 👟 Getting Started with Mercury

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:

`npm`

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

`yarn`

```bash
yarn add @genexus/chameleon-controls-library @genexus/mercury
```

Then follow the installation guide for your selected framework/library:

- <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 (with Vite)](./docs/installation-for-react.md)
- <img src="./docs/images/nextjs.svg" alt="NextJs isotype" width="16"/>&nbsp; [Installation for Next.js](./docs/installation-for-nextjs.md)
- <img src="./docs/images/stencil.svg" alt="Stencil isotype" width="16"/>&nbsp; [Installation for Stencil](./docs/installation-for-stencil.md)

---

> [NOTE]
> The following information is best read **after** completing any of the installation guides above.

## 🎨 One CSS module per Component

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.

### Why one CSS per component?

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.

### How do I import a CSS module?

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.

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 }`.

```ts
// ...non-essential imports for this example omitted
import { getBundles } from "@genexus/mercury/bundles.js";

@Component({
  selector: "my-own-component",
  // ...non-essential code for this example omitted
  template: `<ch-theme [model]="bundles"></ch-theme>
    <div class="field field-block">
      <label class="label" for="name">Phone</label>
      <ch-edit class="input" id="phone" />
    </div>
    <button class="button-primary" type="button">Save Changes</button>`
})
export class CustomDialogComponent {
  bundles = getBundles(
    ["components/button", "components/edit", "utils/form"],
    "{{ CSS bundles final path }}"
  );
}
```

### CSS bundles reference:

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).

| 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](https://mercury-showcase.genexus.com/mercury/components/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](https://mercury-showcase.genexus.com/mercury/components/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](https://mercury-showcase.genexus.com/mercury/components/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)                                                                                   |

## ⚠️ Common issues

The following are some common issues and their solutions you might encounter during installation:

### # Missing Type Declarations in External Dependencies

```bash
Error: ../../node_modules/livekit-client/dist/src/room/PCTransport.d.ts:1:30
error TS7016: Could not find a declaration file for module 'events'.
/genexus/mercury-monorepo/node_modules/events/events.js' implicitly has an 'any' type.
```

Add `skipLibCheck: true` to your `tsconfig.json`

```json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}
```

<details>
<summary>Explanation</summary>
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.
</details>

### # Missing Export Error: 'OverlayEventDetail' Not Found in interfaces.ts (React only)

```bash
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)
```

Update the Stencil-generated files so that the types are imported with `type`.

before

```tsx
import { OverlayEventDetail } from "./interfaces";
```

after

```tsx
import { type OverlayEventDetail } from "./interfaces";
```

<details>
<summary>Explanation</summary>
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.
</details>