README.md 6.18 KB
Newer Older
1
# GitLab UI
2

3
GitLab UI is a UI component library written in [Vue.js](https://vuejs.org).
Andreas Kämmerle's avatar
Andreas Kämmerle committed
4
See https://gitlab-org.gitlab.io/gitlab-ui/ for documentation.
Clement Ho's avatar
Clement Ho committed
5

6
## Usage
George Tsiolis's avatar
George Tsiolis committed
7

8 9
To use GitLab UI in your project, add it as a dependency:

10
```sh
11 12 13
yarn add @gitlab/ui
```

14 15 16
> **Note:** Make sure to also install GitLab UI's peer dependencies. Refer to the
> [`package.json`](./package.json) for the list of peer dependencies and their expected versions.

17 18 19 20 21 22 23 24 25 26
In your main entrypoint **before** importing or using any component:

```javascript
import setConfigs from '@gitlab/ui/dist/config

setConfigs()
```

This will set the global configs used by GitLab UI.

27
Import the components as desired:
28 29 30 31

```javascript
import { GlButton } from '@gitlab/ui';
```
George Tsiolis's avatar
George Tsiolis committed
32

33 34 35 36
GitLab UI is compatible with tree-shaking, you may enable this in your project to reduce bundle sizes.

### GitLab UI CSS

37 38 39 40
GitLab UI provides component styles, a utility-class library, and SCSS utilities.

- [How can I get started with GitLab UI CSS?](doc/css.md)
- [How does GitLab UI interact with GitLab CSS?](doc/debugging-gitlab-ui-with-gitlab-css.md)
41 42 43 44

## Quick start - development

Make sure you have [Node](https://nodejs.org/en/) 8.x (LTS) and [Yarn](https://yarnpkg.com/) 1.2 or newer.
Andreas Kämmerle's avatar
Andreas Kämmerle committed
45

George Tsiolis's avatar
George Tsiolis committed
46 47 48 49
```sh
# Clone the project
git clone [email protected]:gitlab-org/gitlab-ui.git

50 51 52
# Navigate to the root of the project
cd gitlab-ui

George Tsiolis's avatar
George Tsiolis committed
53 54 55 56 57 58 59 60
# Install all the dependencies of the project
yarn # or yarn install

# Build and launch storybook to see the components in the browser
yarn storybook
```

Go to http://localhost:9001/
Clement Ho's avatar
Clement Ho committed
61

62 63
## Testing

64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
### Unit tests

Components’ unit tests live in the `tests/components`. The tests are organized following the same directory structure used to organize components.

`yarn test:unit` runs all unit tests.

`yarn test:unit:watch` runs all unit tests in watch mode.

`yarn test:unit:debug` runs all unit tests and allow to attach a debugger to the test runner process.

`yarn jest [name_pattern]` runs spec files that match the specified name pattern.

#### Examples

`yarn jest datepicker` will match all spec files with a name that contains the word _datepicker_.

`yarn jest datepicker -t "when draw event is emitted"` goes a step further and only runs the test with a description that matches the argument passed to the `t` flag.

### SCSS tests

84
Even though we try to avoid writing complex SASS code to maintain CSS complexity low, we’ve implemented some functions that benefit from automated testing. SASS tests live in the `tests/scss` directory. GitLab UI uses [sass-true](https://www.oddbird.net/true/) to implement these tests, and jest run them.
85 86 87 88 89

`yarn jest run_scss_tests` runs all SCSS tests.

### Visual regression tests

90
GitLab UI uses visual snapshot tests to prevent introducing unexpected regressions with CSS and layout changes on components. The tool we use is [storyshots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core), a storybook addon. Read the project documentation to understand how visual snapshots work.
91 92 93 94 95

There is a visual snapshot of every component’s storybook story. To run the tests, use the `yarn test:visual` command. This command runs on the CI environment and will fail if the component visual appearance changes.

#### Updating visual snapshot baseline images

96
In some occasions, the changes in a component’s appearance are justified. In those cases, we have to update the baseline images to match the new look. See our [visual testing documentation](doc/contributing/visual_testing.md) for how to do that.
97

98
#### GitLab visual regression tests
99

100
GitLab UI components are a reference implementation of the [Pajamas Design System components](https://design.gitlab.com/components/status). These components should conform with the design system specs, and they should look correct in the pajamas website and the GitLab product. Please see [Debugging GitLab UI issues with GitLab product CSS](doc/debugging-gitlab-ui-with-gitlab-css.md) for information on how to debug issues with GitLab product CSS in GitLab UI.
101 102 103

#### Running visual regression tests locally

104 105 106
Visual difference tests form part of the test suite. Rendered output can vary
from host to host (e.g., due to available fonts and how each platform renders
them), so these can fail when run locally. The easiest way to work around this
107 108
is to run a percent-based diff, and to increase the failure threshold with the
`FAILURE_THRESHOLD_TYPE` and `FAILURE_THRESHOLD` environment variables:
109 110 111

```sh
# Sets a 2% threshold
112
FAILURE_THRESHOLD_TYPE='percent' FAILURE_THRESHOLD=.02 yarn test:visual
113 114
```

115 116 117 118 119
`FAILURE_THRESHOLD_TYPE` defaults to `'pixel'` and `FAILURE_THRESHOLD` defaults to `1`. In the CI
environment, we consider a 1 pixel difference as a false negative that should not fail the test.

Under the hood, those variables are passed to
[`jest-image-snapshot`](https://github.com/americanexpress/jest-image-snapshot)'s config
120

George Tsiolis's avatar
George Tsiolis committed
121
## Installation
Clement Ho's avatar
Clement Ho committed
122

123 124 125 126 127 128
Install with Yarn:

```sh
yarn add @gitlab/ui
```

129
Install with npm:
130

George Tsiolis's avatar
George Tsiolis committed
131
```sh
132
npm install @gitlab/ui
George Tsiolis's avatar
George Tsiolis committed
133
```
Andreas Kämmerle's avatar
Andreas Kämmerle committed
134

135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
### Styles

GitLab UI requires its styles to be imported to display components properly. We currently have 2
separate stylesheets that both need to be included in your project. The main stylesheet
(`gitlab_ui.scss`) contains component-specific styles, while the other one (`utilities.scss`)
contains the utility classes library on which some components rely. You might find the utility
classes useful to layout components in your own project.

You have two options to include those stylesheets:

- If you have a SCSS preprocessor setup, include the SCSS files in your own stylesheet:

```scss
@import '@gitlab/ui/src/gitlab_ui.scss';
@import '@gitlab/ui/src/utilities.scss';
```

- If you don't have a SCSS preprocessor setup, you can import the compiled CSS files directly:

```css
@import '@gitlab/ui/dist/index.css';
@import '@gitlab/ui/dist/utility_classes.css';
```

159
## Releases
160

161 162
Please see [Updating Gitlab UI Packages](doc/updating-gitlab-ui-packages.md) for information on how updated packages are included in Gitlab and Pajamas.

163
## Contributing guide
Andreas Kämmerle's avatar
Andreas Kämmerle committed
164

165
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to add new components and contribute in general to GitLab UI.
166 167 168 169

### FAQs

Any question? Have a look at our [FAQ.md](FAQ.md), you might find the answer there.