@genexus/chameleon-controls-library

Chameleon

A library of white-label, highly-customizable and reusable web components.

Visit the Chameleon Showcase for general information, demos and documentation.

Using this library

There are four strategies we recommend for using these web components.

In frameworks (React, Angular, etc) using a design system like Mercury or Unanimo.

For this, we recommend consulting our repository chameleon-integrations that contains various examples demonstrating how to effectively use the Chameleon Controls Library in different frameworks and with different design systems.

React

• Run

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

• Starting with Chameleon version 6.4.0, there is a CLI to create React Web Component wrappers. To create the wrappers, run the following command:

  npx chameleon-generate-react <output dir (optional)>
  

  For example:

  npx chameleon-generate-react ./src/chameleon-components
  

• Tip: We recommend adding this command to your package.json file before running the dev server and production builds, as it takes less than 300ms to execute.

  For example:

  "dev": "npm run build.chameleon && ...",
  "build": "npm run build.chameleon && ..."
  "build.chameleon": "chameleon-generate-react <output dir (optional)>"
  

  If you are in a monorepo environment, you may need run the script with npx chameleon-generate-react, yarn chameleon-generate-react, etc.

• Finally, all you have to do is use the components in your project!

In a Stencil project

• Run

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

• Add an import to the library inside src/index.ts:

  import "@genexus/chameleon-controls-library";
  

• Then you can use the web components anywhere in your template, JSX, html etc

Node Modules

• Run

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

• Put a script tag similar to this <script src="node_modules/@genexus/chameleon-controls-library/dist/chameleon/chameleon.esm.js"></script> in the head of your index.html

• Then you can use the web components anywhere in your template, JSX, html etc

Script tag

• Put a script tag similar to this <script src="https://unpkg.com/@genexus/chameleon-controls-library@latest/dist/chameleon/chameleon.esm.js"></script> in the head of your index.html

• Then you can use the web components anywhere in your template, JSX, html etc

Accessibility checker

Starting with Chameleon version 6.4.0 there is a new accessibility utility that checks if form elements have a valid label and notifies (console.warn) when they don't accomplish this condition. At this moment, it's supported in the following components:

• ch-combo-box-render
• ch-edit
• ch-progress
• ch-slider

The accessibility checker is enabled by default and can be disabled as follows:

import { disableAccessibilityReports } from "@genexus/chameleon-controls-library/dist/collection";

disableAccessibilityReports();

Meaning of development status in each control

Category	Description
"experimental"	The control is in its early stages of the development. This phase is often useful for testing the control early, but it is very likely that the interface will change from the final version. Breaking changes for the control can be applied in "patch" tags.
"developer-preview"	The control is in its final stages of the development. The interface and behaviors to implement the control are almost complete. The interface of the control should not change so much from the final version. Breaking changes for the control can be applied in "patch" tags.
"stable"	The control's development is stable and can be safety used in production environments. Breaking changes for the control can be applied in "major" tags. In some cases, two "major" tags would be used to deprecate a behavior in the control.

Local Development

npm i
npm start

Running the tests

To run the unit tests for the custom elements, run:

npm test

To run the spec tests for a specific custom element, run:

npm run test.spec src/components/<path to test file.spec.ts>

## For example:

npm run test.spec src/components/layout-splitter/tests/fixAndUpdateLayoutModel.spec.ts

To watch changes for tests (spec and e2e), run:

npm run test.watch

To watch only one file, run:

npm run test.watch -- -- src/components/edit/<path to test file.<spec|e2e>.ts>

## For example:

npm run test.watch -- -- src/components/edit/tests/edit.e2e.ts

To watch only one folder, run:

npm run test.watch -- -- <folder path>

## For example:

npm run test.watch -- -- src/components/edit/tests/

Building for production

To build the design for production, run:

npm run build