# UX.UI Component Library - Core ## 🖥 Environment Support | [IE / Edge](http://godban.github.io/browsers-support-badges/)
Edge | [Firefox](http://godban.github.io/browsers-support-badges/)
Firefox | [Chrome](http://godban.github.io/browsers-support-badges/)
Chrome | [Safari](http://godban.github.io/browsers-support-badges/)
Safari | [Opera](http://godban.github.io/browsers-support-badges/)
Opera | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Edge | last 2 versions | last 2 versions | last 2 versions | latest 2 versions ## Usage ### Installation Add a single script reference to the page head and the library is ready to go. Each component you use is lazy-loaded when you first use one. ### CDN ```html ``` ### Bash ```bash npm install --save @trumpf/ux.ui ``` ## ⌨️ Development ```bash $ git clone https://gitlab.com/TRUMPF-corp/trumpf-ux/features/com.trumpf.ux.ui-core.git $ cd com.trumpf.ux.ui-core $ npm ci $ npm run start ``` ## 💬 Commit Messages This repository follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), based on the Angular convention. Each commit message should use following pattern: ``` [optional scope]: [optional body] [optional footer(s)] ``` **type** (required) - is one of: - `build` - changes that affect the build system or external dependencies - `chore` - no production code change - `ci` - changes to CI configuration files and scripts - `docs` - documentation only changes - `feat` - introduces a new feature to the codebase (correlates with MINOR in Semantic Versioning) - `fix` - patches a bug in your codebase (correlates with PATCH in Semantic Versioning) - `perf` - code change that improves performance - `refactor` - code change that neither fixes a bug nor adds a feature - `revert` - commit, which reverts another commit - `style` - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) - `test` - adding missing tests or correcting existing tests **scope** (optional) - definition of a change area. At best, it should contain the name of a changed component. **description** (required) - brief description of a change in commit. Rules for a commit message: - use the imperative, present tense: "change" not "changed" nor "changes" - don't capitalize the first letter - no dot (.) at the end **body** (optional) - full description of a change. Same message rules are applying, as for _description_. The body should include the motivation for the change and contrast this with previous behavior. **footer** (optional) - should contain any information about Breaking Changes. Breaking Changes should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. [Complete list of commit message linting rules](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) ### 📦 Distribution Deployments take place after each successful merge of the `master` branch.
The built NPM artifact is deployed in the Artifactory (JFrog) in the `@trumpf` namespace.
The generated storybook instance is deployed via AWS. | Platform | Link | |-----------|----------------------------------------------------------------------------| | Storybook | http://customerui-styleguide.s3-website.eu-central-1.amazonaws.com/master/ | | JFrog | https://artifactory.corp.trumpf.com/ui/repos/tree/General/trumpf.ux.npm | # Dev Environment Although you may use the locally installed version of Node and npm, it is advised to use a provided Docker container to mitigate differences in local environments. For visual regression tests it is **highly recommended** to use Docker container. ### Use of the TRUMPF proxies In some situations using Artifactory is not a viable solution. If npm has to reload further artifacts from the Internet during the installation, it tries a direct connection again, which will fail due to a lack of proxy settings. In this case npm can be induced to use the TRUMPF proxy. To do this, you can set the environment variables `http_proxy` and `https_proxy`. At the same time, however, Artifactory must be included in the proxy exceptions. **On a Windows system, the environment variables must be set as follows:** ``` http_proxy=http://srv01prox.corp.trumpf.com:80 https_proxy=http://srv01prox.corp.trumpf.com:80 no_proxy=srv01af2.corp.trumpf.com ``` ## Testing Documentation This section outlines the testing procedures for the project, highlighting the use of provided run configurations in IntelliJ and VSCode. The testing is designed to be interactive and developer-friendly, allowing for efficient debugging and issue resolution. ## Run Configurations Two main configurations are provided for testing (.run folder or in .vscode folder): 1. **Test:Stencil:E2E:CurrentFile** - This configuration allows you to run end-to-end tests on the currently active file. It is ideal for focused testing of individual components or features. 2. **Test:Stencil:E2E** - Use this configuration to execute end-to-end tests across the entire project. It ensures comprehensive coverage and is essential for final checks before deployment. Additional utilities include (IntelliJ only): - **Run:Storybook:Stencil:Serve** - For visually testing and interacting with Stencil components in isolation. - **Lint:Fix** - To automatically fix linting issues and maintain code quality standards. ## Configuration in `stencil.config.json` To enhance the testing experience, it is recommended to adjust the `stencil.config.json` as follows: ``` testing: { browserHeadless: false, browserDevtools: true, browserSlowMo: 1000, }, ``` These settings allow for testing with browser DevTools enabled, providing a non-headless mode for visual feedback and a slowed-down execution (1000ms) to observe interactions and animations. ## Debugging For debugging in end-to-end (E2E) tests, insert the following code snippet where you need a breakpoint: ```javascript await page.evaluate(() => { debugger; }); ``` This will pause the execution in the browser, allowing you to use browser DevTools for debugging. It is especially useful for examining the state of the application at specific points during test execution. Ensure your browser's developer tools are open before the test reaches the breakpoint to pause execution effectively. --- ### Docker environment To be able to use it you need a Docker installed on your machine: https://docs.docker.com/get-docker/ It is recommended to make a **12 Gb of RAM** for a Docker available. You can configure it via Docker Desktop under Preferences -> Resources -> Advanced After that you need to authorize the Docker to get the Images from TRUMPF Gitlab registry. For this visit the "Access Tokens" page of your User Settings in Gitlab: https://gitlab.com/-/profile/personal_access_tokens Create a new token: 1. Give a **Token Name** - it will be used later as login 2. Select **read_registry** scope 3. Click on **Create Personal Access Token** 4. A created **Token** will be displayed - it will be used later as a password Login to a TRUMPF Gitlab Docker registry: 1. Run `docker login registry.gitlab.com` 2. Insert **Token Name** as a username 3. Insert **Token** as a password After that you're ready and can start the environment with: ``` docker-compose up -d ``` On a first run it may take up to 10-15 minutes to start, because all the npm dependencies will be installed and project compiled. You may track the progress of a startup by using: ``` docker-compose logs -f ``` After the startup is finished you need to open http://localhost:4100/ to see the Storybook. You may run any npm command against the container. For example run Visual Regression Tests: ``` docker-compose exec ux-ui npm run test-regression ``` Please allocate at least 12GB of RAM for Docker in order to avoid memory leakages. If you cannot allocate 12GB of RAM for Docker we suggest that you only run the test for the component(s) you are currently working on, with the command: ``` docker-compose exec ux-ui npm run stencil-test-regression-coverage src/components/component/path/to/test-file.e2e.ts ``` ### Pipeline issues Sometimes there are problems with the `install` pipeline. The first step then fails. Often, the problem is that wrong urls are used in the `package-lock.json`. First please make sure that the content of your `.npmrc` file is correct. To generate it, please use your jfrog artifactory credentials. If the pipeline fails anyway, check your `package-lock.json` for the following url: * *https://srv01af2.corp.trumpf.com:443/artifactory/api/npm/npmjs-registry-npm** If this url is present, replace that part with: **https://registry.npmjs.org** and push your changes.