@mozaic-ds/vue-3/README.md

Vue.js implementation of Mozaic Design System

<h1 align="center">
  <img width="400" src="https://adeo.github.io/mozaic-vue/static/media/logo-mozaic-vue-large.fb8f5358.svg" alt="Mozaic Vue.js" />
</h1>

## Introduction

**Mozaic-Vue** is the [Vue.js](https://vuejs.org/) implementation of [Mozaic Design System](https://mozaic.adeo.cloud/)

Note that this package is built to be used with **Vue.js version 3**.

You can have an overview of each component of this library by visiting the dedicated **Storybook**: [Storybook](https://master--641e94a45750cc9b0f477973.chromatic.com)

## Installation

> PREREQUISITE: To allow you to include and use our package in your library, we assume that you are using a module bundlers like [Webpack](https://webpack.js.org/), [Parcel](https://parceljs.org/) or [rollup.js](https://rollupjs.org/guide/en/), or that your project has been initiated with [Vue CLI](https://cli.vuejs.org/). Otherwise, the package might not work.

In order to use **Mozaic-Vue** in your **Vue.js** project, you must first install the npm package:

```shell
$ npm install @mozaic-ds/vue-3 --save --save-exact
```

Or with **Yarn**:

```shell
$ yarn add @mozaic-ds/vue-3 -E
```

## Usage

**Mozaic-Vue** is a component library that responds to the different usage contexts proposed by **Vue.js**.

Indeed, as indicated in [its documentation](https://vuejs.org/guide/components/registration.html#global-registration), **Vue.js** proposes to register/use the components in a global or local way:

- The global import allows you to make your components accessible throughout your application
- The local import, on the other hand, makes a component accessible only in the part of the application that uses it

> Learn more about the notion of global/local registration on [the Vue.js documentation](https://vuejs.org/guide/components/registration.html#global-registration)

### Global import

#### Import all components

The easiest way to start using **Mozaic-Vue**, is to import all the components and make them available throughout your application.

To do this, in your entry point file, insert the following code:

```javascript
// In the entry point file of your application - usually src/main.js

import MozaicVue from '@mozaic-ds/vue-3';
import '@mozaic-ds/vue-3/dist/mozaic-vue.css'; // Import the css of all components (158ko)

const app = createApp(App);
app.use(MozaicVue);
```

> NOTE: If you are working on a project that requires the use of the ADEO theme, you should use the following style sheet: `import '@mozaic-ds/vue-3/dist/mozaic-vue.adeo.css';`

#### Import only the desired components

If you do not want to use all the components of the library, but only some of them, you can proceed as follows:

```javascript
// In the entry point file of your application - usually src/main.js

import { MAccordion, MButton } from '@mozaic-ds/vue-3';
import '@mozaic-ds/vue-3/dist/mozaic-vue.css'; // Import the css of all components (158ko)

Vue.use(MAccordion);
Vue.use(MButton);
```

> NOTE: As you can see, the way to import the CSS is the same for both the import of individual components and the import of all components. Indeed, it is not possible to split the generated CSS file. If you want to import only the CSS related to your individual component import, it may be better to use the local import method described below.

#### Use the component

That's it! You are now able to use the **Mozaic** components in your **Vue.js** project.

Simply call the component of your choice at the desired location anywhere in your application:

```html
<MButton label="Default button" />
```

### Local import

If you want to import a component locally, you can proceed as follows:

```javascript
// In one the .vue file of your application

<script>
...
import { MButton } from '@mozaic-ds/vue-3/src/components/button';
...
components: {
  MButton,
},
...
</script>
```

By doing this import you will be able to get the HTML & JS part of the desired **Mozaic** component.

#### About the CSS of locally imported components

Concerning the style part, you should know that Mozaic components embed their styles in **SCSS** format; and that **Mozaic** uses **PostCSS** to interpret and build the final CSS.

Therefore, for your local import to work perfectly, **you still need to perform one last step**, namely to create a `vue.config.js` file at the root of your project.

Inside this file, you will have to configure your module bundler to use **PostCSS** to interpret the **SCSS** of **Mozaic** components.

For that, we recommend you to get the code present in the following file: [Custom vue.config.js](https://github.com/adeo/mozaic-vue/blob/master/packages/vue3/vue.config.js)

Then insert it in your `vue.config.js` file.

#### Use the component

That's it! You are now able to use the **Mozaic** components in your **Vue.js** project.

Simply call the component as follows:

```html
<MButton label="Default button" />
```